Language Mapping

This guide explains how TMGMT Lara Translate maps Drupal language codes to Lara Translate locale codes for proper translation support.

Overview

Drupal uses ISO 639-1 (2-letter) language codes (en, it, de) while Lara Translate uses full locale codes (en-US, it-IT, de-DE). The module implements a hybrid mapping approach that provides sensible defaults while allowing customization.

Mapping Strategy

1. Default Static Mappings

The module includes built-in mappings for all languages supported by Lara Translate:

Single Variant Languages

Languages with one primary variant use direct mapping:

'en' => 'en-US',  // English (US default)
'es' => 'es-ES',  // Spanish (Spain default)
'fr' => 'fr-FR',  // French (France default)
'it' => 'it-IT',  // Italian (Italy default)
'de' => 'de-DE',  // German (Germany default)

Multi-Variant Languages

Languages with regional variants default to the most common variant:

'pt' => 'pt-PT',  // Portuguese (Portugal default)
'zh' => 'zh-CN',  // Chinese Simplified (default)

2. Custom Configuration Mappings

Site administrators can override defaults for specific needs:

Use Cases

Regional preferences: en → en-GB for British English
Custom locales: Map to specific Lara-supported variant
Language variants: Handle multiple dialects of same language

Configuration via UI

Go to Configuration → Translation Management → Providers
Edit your Lara translator configuration
Expand Language mappings section
Add mappings as: drupal_code → lara_code

Configuration Format

language_mappings:
  en: en-GB           # Use British English instead of American
  zh: zh-TW           # Use Traditional Chinese instead of Simplified
  pt-br: pt-BR          # Map Brazilian Portuguese specifically

Complete Language Mapping Table

Drupal Code	Lara Code	Language
`ar`	`ar-SA`	Arabic (Saudi Arabia)
`bg`	`bg-BG`	Bulgarian
`ca`	`ca-ES`	Catalan
`cs`	`cs-CZ`	Czech
`da`	`da-DK`	Danish
`de`	`de-DE`	German
`el`	`el-GR`	Greek
`en`	`en-US`	English (US) ⭐
`en-au`	`en-AU`	English (Australia)
`en-ca`	`en-CA`	English (Canada)
`en-gb`	`en-GB`	English (UK)
`en-ie`	`en-IE`	English (Ireland)
`es`	`es-ES`	Spanish (Spain) ⭐
`es-ar`	`es-AR`	Spanish (Argentina)
`es-mx`	`es-MX`	Spanish (Mexico)
`fi`	`fi-FI`	Finnish
`fr`	`fr-FR`	French (France) ⭐
`fr-ca`	`fr-CA`	French (Canada)
`he`	`he-IL`	Hebrew
`hr`	`hr-HR`	Croatian
`hu`	`hu-HU`	Hungarian
`id`	`id-ID`	Indonesian
`it`	`it-IT`	Italian
`ja`	`ja-JP`	Japanese
`ko`	`ko-KR`	Korean
`ms`	`ms-MY`	Malay
`nb`	`nb-NO`	Norwegian Bokmål
`nl`	`nl-NL`	Dutch (Netherlands) ⭐
`nl-be`	`nl-BE`	Dutch (Belgium)
`pl`	`pl-PL`	Polish
`pt`	`pt-PT`	Portuguese (Portugal) ⭐
`pt-br`	`pt-BR`	Portuguese (Brazil)
`ru`	`ru-RU`	Russian
`sk`	`sk-SK`	Slovak
`sv`	`sv-SE`	Swedish
`th`	`th-TH`	Thai
`tr`	`tr-TR`	Turkish
`uk`	`uk-UA`	Ukrainian
`zh-hans`	`zh-CN`	Chinese Simplified
`zh-hant`	`zh-TW`	Chinese Traditional
`zh-hk`	`zh-HK`	Chinese (Hong Kong)

⭐ = Default variant for multi-variant languages

Implementation Details

Mapping Method Logic

private function mapDrupalToLaraLanguage(string $drupal_langcode, TranslatorInterface $translator): ?string {
    // 1. Check for custom mapping first
    $custom_mappings = $translator->getSetting(['language_mappings']) ?? [];
    if (isset($custom_mappings[$drupal_langcode])) {
        return $custom_mappings[$drupal_langcode];
    }

    // 2. Fall back to default static mapping
    return $this->getDefaultLanguageMapping()[$drupal_langcode] ?? null;
}

Validation Process

private function isLanguagePairSupported(string $source_langcode, string $target_langcode, TranslatorInterface $translator): bool {
    $lara_source = $this->mapDrupalToLaraLanguage($source_langcode, $translator);
    $lara_target = $this->mapDrupalToLaraLanguage($target_langcode, $translator);

    if ($lara_source === null || $lara_target === null) {
        return false;
    }

    $supported_languages = $this->getSupportedLaraLanguages($translator);
    return in_array($lara_source, $supported_languages) && 
           in_array($lara_target, $supported_languages);
}

Configuration Schema

Language mappings are validated through configuration schema:

# tmgmt_laratranslate.schema.yml
language_mappings:
  type: sequence
  label: 'Custom Language Code Mappings'
  sequence:
    type: mapping
    mapping:
      drupal_code:
        type: string
        label: 'Drupal Language Code'
      lara_code:
        type: string
        label: 'Lara Language Code'

Configuration Examples

British English Site

For sites targeting UK audience:

language_mappings:
  en: en-GB        # Override default en-US
  de: de-AT        # Austrian German instead of Germany German

Multi-Regional Site

For sites serving multiple regions:

language_mappings:
  en: en-US          # Default for most users
  en-gb: en-GB        # Available for UK users
  fr: fr-CA          # Canadian French
  pt: pt-BR          # Brazilian Portuguese

Custom Language Codes

For languages with specific locale requirements:

language_mappings:
  en: en-AU           # Australian English
  zh-hans: zh-SG      # Singapore Simplified Chinese
  es-mx: es-MX        # Mexican Spanish

Troubleshooting Language Mapping

Common Issues

"Language pair not supported"

Cause: No mapping exists for one or both language codes

Solutions: 1. Check Drupal language codes: drush config:get system.site default_langcode 2. Verify custom mappings in translator configuration 3. Confirm Lara supports the target locale codes

Incorrect regional variant

Cause: Wrong regional variant mapped

Example: Site needs en-GB but maps to default en-US

Solution:

language_mappings:
  en: en-GB        # Override default

Missing custom mapping

Cause: Custom mapping not found in configuration

Debugging:

# Check current configuration
drush config:get tmgmt.translator.lara_translate

# Test mapping manually
drush php -r "
\$translator = \Drupal::entityTypeManager()->getStorage('tmgmt_translator')->load('lara_translate');
\$plugin = \$translator->getPlugin();
echo \$plugin->mapDrupalToLaraLanguage('custom_lang_code', \$translator);
"

Validation Errors

"Invalid language code"

Cause: Lara doesn't support the mapped locale code

Common mistakes: - en-EU (not a valid Lara locale) - xx-XX (made-up language code) - zh-CN-CN (redundant region)

Solution: Use only supported Lara locale codes from the table above

API Integration

Supported Languages Query

// Get languages supported by Lara API
$lara_translator = $this->createLaraTranslator($translator);
$supported_languages = $lara_translator->getLanguages();

// Filter by Drupal site languages
$site_languages = \Drupal::languageManager()->getLanguages();
$available_languages = array_intersect($supported_languages, array_keys($this->languageMapping));

Translation Requests

When submitting translation jobs, the module: 1. Maps Drupal source → Lara source code 2. Maps Drupal target → Lara target code 3. Validates both codes exist in Lara's supported languages 4. Sends translation request with mapped codes

Best Practices

Configuration Guidelines

Use defaults when possible: Default mappings are well-tested
Map regions appropriately: Consider your audience
Document custom mappings: Explain why overrides are needed
Test language pairs: Verify translations work after mapping changes

Migration Considerations

When migrating from other translation systems: 1. Audit existing content: Check language codes used 2. Plan mapping strategy: Define needed overrides 3. Test with sample content: Verify translations work correctly 4. Monitor for errors: Watch for mapping-related failures

Maintenance

Review periodically: Ensure mappings stay relevant
Update when adding languages: Add new mappings as needed
Remove unused mappings: Keep configuration clean
Document decisions: Record why specific mappings were chosen

Advanced Usage

Programmatic Mapping

// Set mappings via code
$translator = \Drupal::entityTypeManager()->getStorage('tmgmt_translator')->load('lara_translate');
$translator->setSetting(['language_mappings'], [
    'en' => 'en-GB',
    'fr' => 'fr-CA',
    'custom' => 'xx-XX',
]);
$translator->save();

Dynamic Language Detection

For advanced use cases, implement custom logic:

// Example: Map based on user location
function mapUserLanguage(string $drupal_code, string $country): string {
    $mappings = [
        'US' => 'en-US',
        'GB' => 'en-GB',
        'CA' => 'en-CA',
    ];

    return $mappings[$country] ?? 'en-US';
}

Configuration Guide - Setup and configuration
Architecture Overview - Implementation details
Troubleshooting Guide - Common issues and solutions