Tradução no Business Central na Prática: Do XLF à Publicação

A tradução correta de uma extensão no Microsoft Dynamics 365 Business Central vai muito além de simplesmente converter textos para outro idioma. Ela impacta diretamente a experiência do usuário, a padronização do sistema e a qualidade final da solução.

Neste artigo, compartilho o fluxo completo que utilizo em projetos reais, desde a geração dos arquivos XLF até a manutenção contínua das traduções ao longo do ciclo de vida do app.

O objetivo é apresentar um processo claro, repetível e acessível tanto para desenvolvedores quanto para consultores.

Pré-requisitos

Antes de iniciar o processo de tradução, é necessário ter o ambiente configurado.

Requisitos básicos:

• Visual Studio Code

• Extensão AL Language

• Projeto de extensão funcionando

• Ambiente Business Central (Sandbox ou Container)

• Node.js (versão LTS)

• Biblioteca ngx-i18nsupport (xliffmerge)

Instalação do xliffmerge no projeto:

Dentro da pasta do projeto:

npm install ngx-i18nsupport --save-dev

Execução:

npx xliffmerge

Essa abordagem evita dependências globais e facilita o uso em equipe e em pipelines.

Habilitando Traduções no Projeto

Para que o AL gere os arquivos de tradução, é necessário habilitar a feature no app.json:

Após a compilação do projeto, será criada automaticamente a pasta Translations, contendo o arquivo base (*.g.xlf).

"features": [
"TranslationFile"
]

Arquivo Base (.g.xlf)

O arquivo .g.xlf contém todos os textos extraídos do código, como:

• Caption

• ToolTip

• Labels

Esse arquivo é recriado a cada build e serve apenas como base. Ele não deve ser traduzido diretamente.

Sempre que novos textos são adicionados ao código, o .g.xlf é atualizado.

Mantendo Traduções com XLIFFMerge

Durante o desenvolvimento, novos textos são adicionados, alterados ou removidos. Para evitar a perda de traduções existentes, utilizamos o xliffmerge, responsável por consolidar o arquivo base gerado pelo AL (*.g.xlf) com os arquivos já traduzidos.

Criando o arquivo package.json

• i18nFile (Nome do arquivo base gerado pelo AL.)

  • Normalmente será <NomeDoApp>.g.xlf (Esse é o arquivo que contém apenas os textos fonte.)

• i18nBaseFile (Define o nome base do arquivo de tradução gerado.)

  • Se estiver configurado como "NomeDoApp", o resultado será "NomeDoApp.pt-BR.xlf"

• languages (Define os idiomas de destino.)

  • Você pode configurar um ou mais idiomas dentro dos colchetes [], separados por vírgula, o xliffmerge irá gerar um arquivo para cada idioma listado. Exemplo: ["pt-BR", "es-ES"]

• defaultLanguage

  • Normalmente é "en-US". Isso porque o Business Central padrão (W1) utiliza inglês como idioma base. Se o seu projeto foi desenvolvido originalmente em outro idioma, o defaultLanguage deve refletir o idioma real do código fonte.

{
"xliffmergeOptions": {
"srcDir": "Translations",
"genDir": "Translations",
"i18nFile": "YourAppName.g.xlf",
"i18nBaseFile": "YourAppName",
"i18nFormat": "xlf",
"encoding": "UTF-8",
"defaultLanguage": "en-US",
"languages": ["pt-BR"],
"removeUnusedIds": true,
"useSourceAsTarget": true,
"preserveOrder": true,
"allowIdChange": false
}
}

Na raiz do projeto, crie um arquivo chamado:

• package.json

Adicione a seguinte estrutura:

Explicação dos principais parâmetros

Executando o merge

Após configurar o package.json, execute no terminal do projeto:

• npx xliffmerge

O arquivo de tradução será criado ou atualizado automaticamente na pasta Translations.

Fluxo de Atualização Contínua

Sempre que novos textos forem adicionados ao código:

1. Compilar o projeto

2. Executar xliffmerge

3. Atualizar as traduções

4. Recompilar

Esse fluxo garante a consistência ao longo do tempo.

Tradução com Ferramentas Tradicionais

Tradicionalmente, ferramentas como o Poedit são utilizadas para editar arquivos XLF.

Elas permitem:

• Visualização de source e target

• Marcação de entradas pendentes

• Memória básica de tradução

• Validação dos arquivos

Esse modelo funciona bem para projetos menores ou com baixa complexidade.

BC XLF Translator: Uma Alternativa Focada no Business Central

Ao longo de projetos maiores, identifiquei limitações nas ferramentas genéricas, principalmente em cenários com grande volume de textos, múltiplos ciclos de revisão e necessidade de padronização.

Com isso, desenvolvi uma ferramenta própria chamada BC XLF Translator, focada especificamente em traduções para o Business Central.

Trata-se de uma aplicação desktop, offline, voltada para produtividade e manutenção contínua.

Principais funcionalidades:

• Agrupamento automático de traduções por similaridade

• Tradução única aplicada a múltiplas entradas

• Translation Memory por combinação de idiomas (ex: en-US → pt-BR)

• Processamento automático baseado no histórico já traduzido

• Reaproveitamento inteligente de traduções existentes

• Foco em produtividade em projetos grandes

O objetivo da ferramenta é reduzir retrabalho, manter consistência terminológica e acelerar ciclos de tradução.

Disponibilidade

A ferramenta BC XLF Translator está disponível gratuitamente no meu GitHub:

Download BC XLF Translator

Novas funcionalidades e melhorias são adicionadas continuamente.

Boas Práticas para Tradução no Business Central

Com base na experiência prática, destaco alguns pontos importantes:

• Utilize sempre Labels

  • Evite textos “hardcoded” no código.

• Padronize termos

  • Mantenha um glossário para evitar variações.

• Use merge em todo ciclo

  • Nunca traduza diretamente o .g.xlf.

• Versione seus arquivos

  • Inclua traduções no controle de versão.

• Revise antes de publicar

  • Erros de tradução impactam diretamente o usuário final.

Problemas Comuns

• ❌ XLF vazio

  • Verifique se existem Labels ou Captions no código.

• ❌ Tradução não aparece

  • Confirme se recompilou o app após salvar o XLF.

• ❌ IDs quebrados

  • Evite alterar IDs manualmente.

• ❌ Traduções perdidas

  • Geralmente causado por falta de uso do xliffmerge.

Conclusão

A tradução no Business Central deve ser tratada como parte do ciclo de desenvolvimento, e não como uma etapa isolada.

Com o uso correto do .g.xlf, do xliffmerge e de ferramentas adequadas, é possível manter soluções bem localizadas, consistentes e fáceis de evoluir.

Espero que este conteúdo ajude outros desenvolvedores e parceiros a estruturar melhor seus processos de tradução.