/skill-translate

name: skill-translate
description: "AL translation and localization for Business Central. Use when working with XLF files, NAB tools, or implementing multi-language support in extensions."

Skill: AL Translation Management

Purpose

Manage multilingual translations for AL extensions using XLF files: create and refresh language files, batch-translate with NAB AL Tools, preserve placeholders, enforce character limits, maintain terminology consistency, and implement quality review workflows.

When to Load

This skill should be loaded when:

• A new target language needs to be added to an AL extension
• Untranslated texts need to be translated after code changes
• Translation quality review is needed (placeholder validation, character limits)
• Regional language variations must be managed (es-ES vs es-MX)
• Incremental translation is required after refreshing XLF files

Core Patterns

Before adopting BC29 namespace-aware translations, read the translation section of [AL18 capability checks](../skill-migrate/references/al18-capabilities.md). Verify `TranslationsWithNamespaces` in the installed schema and compare generated XLF IDs and retained translations before changing an existing project's setting.

Pattern 1: Create Language File

Create a new XLF translation file from the generated source:

createLanguageXlf
  generatedXlfFilePath: "Translations/MyApp.g.xlf"
  targetLanguageCode: "es-ES"
  matchBaseAppTranslation: true    // pre-populate from Microsoft base translations

**Rules:**

• The `.g.xlf` file is auto-generated by the AL compiler — never edit it manually
• `matchBaseAppTranslation: true` copies existing Microsoft translations for standard terms
• One language file per locale: `MyApp.es-ES.xlf`, `MyApp.fr-FR.xlf`, etc.

Pattern 2: Refresh and Retrieve Texts

After code changes, sync the language file and get new untranslated texts:

// Step 1: Refresh — adds new entries, preserves existing translations
refreshXlf
  generatedXlfFilePath: "Translations/MyApp.g.xlf"
  filePath: "Translations/MyApp.es-ES.xlf"

// Step 2: Get untranslated texts with context
getTextsToTranslate
  filePath: "Translations/MyApp.es-ES.xlf"
  limit: 50
  offset: 0

Each text entry includes:

• `id` — unique identifier for the translation unit
• `source` — original text to translate
• `type` — context: `Table Customer - Field Name - Property Caption`
• `maxLength` — character limit (if set in AL source)
• `comments` — notes about placeholders (%1, %2)

Pattern 3: Batch Translation

Translate multiple texts in a single operation:

saveTranslatedTexts
  filePath: "Translations/MyApp.es-ES.xlf"
  translations: [
    {
      "id": "Table_ContosoProject_Field_Description_Caption",
      "targetText": "Descripción",
      "targetState": "translated"
    },
    {
      "id": "Page_ContosoProjectCard_Action_Release_Caption",
      "targetText": "Lanzar",
      "targetState": "translated"
    },
    {
      "id": "Codeunit_ContosoMgt_Error_CustomerNotFound",
      "targetText": "Cliente %1 no encontrado.",
      "targetState": "translated"
    }
  ]

**Translation rules:** 1. **Preserve placeholders** — `%1`, `%2`, `%3` must appear in the same order 2. **Respect `maxLength`** — abbreviate if needed, never exceed 3. **Match context** — same English word may have different translations depending on `type` 4. **Follow Microsoft terminology** — use base app translations for standard BC terms

Pattern 4: Translation Quality Review

Use translation states to implement a review workflow:

| State | Meaning | Who | |---|---|---| | `translated` | Initial translation done | Translator | | `needs-review-translation` | Flagged for review | Translator / QA | | `final` | Reviewed and approved | Reviewer | | `signed-off` | Production-ready | Language lead |

// Find texts needing review
getTranslatedTextsByState
  filePath: "Translations/MyApp.es-ES.xlf"
  translationStateFilter: "needs-review-translation"
  limit: 0

// After review, promote to final
saveTranslatedTexts
  filePath: "Translations/MyApp.es-ES.xlf"
  translations: [
    { "id": "...", "targetText": "...", "targetState": "final" }
  ]

**Common quality issues:**

// Issue 1: Missing placeholder
❌ Source: "Posted %1 of %2"
❌ Translation: "Registrado %2"         // missing %1
✅ Translation: "Registrado %1 de %2"

// Issue 2: Character limit exceeded
❌ Source: "Post" (maxLength: 10)
❌ Translation: "Registrar y contabilizar"  // 25 chars
✅ Translation: "Registrar"                 // 9 chars

// Issue 3: Context-dependent meaning
Source: "Post"
Context: Action caption → "Registrar" ✅
Context: Table name     → "Correo"    ✅  (different meaning!)

Pattern 5: Translation Memory and Glossary

Use existing translations for consistency:

// Get all translated texts as a reference map
getTranslatedTextsMap
  filePath: "Translations/MyApp.es-ES.xlf"
  limit: 0

// Search for specific terms across translations
getTextsByKeyword
  filePath: "Translations/MyApp.es-ES.xlf"
  keyword: "Customer|Vendor|Invoice"
  isRegex: true
  caseSensitive: false
  searchInTarget: true

**Glossary approach:**

• Before translating a batch, retrieve existing translations with `getTranslatedTextsMap`
• Search for related terms with `getTextsByKeyword` to ensure consistent terminology
• Standard BC terms should match Microsoft's official base app translations

Pattern 6: Regional Variations

Manage locale-specific translations (e.g., es-ES vs es-MX):

// Step 1: Create base translation (es-ES)
createLanguageXlf
  generatedXlfFilePath: "Translations/MyApp.g.xlf"
  targetLanguageCode: "es-ES"
  matchBaseAppTranslation: true

// Step 2: Create regional variant from base
createLanguageXlf
  generatedXlfFilePath: "Translations/MyApp.g.xlf"
  targetLanguageCode: "es-MX"
  matchBaseAppTranslation: true

// Step 3: Get base translations as reference
getTranslatedTextsMap
  filePath: "Translations/MyApp.es-ES.xlf"
  limit