Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

skill-translate

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

javiarmesto · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add javiarmesto/ALDC-AL-Development-Collection --skill skill-translate

About this skill


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. 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:

StateMeaningWho
translatedInitial translation doneTranslator
needs-review-translationFlagged for reviewTranslator / QA
finalReviewed and approvedReviewer
signed-offProduction-readyLanguage 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: 
Read the complete source ↗