Alfa
O Lingo.dev Compiler está em alfa. É instável, não é recomendado para utilização em produção e as APIs podem mudar entre versões.
O Lingo.dev Compiler funciona com dois modos de build que determinam se são geradas novas traduções durante o build. Compreender estes modos é essencial para configurar um pipeline fiável de desenvolvimento, CI e produção.
Os dois modos#
| Modo | Comportamento | Quando utilizar |
|---|---|---|
"translate" | Gera traduções em falta ao recorrer ao fornecedor de LLM configurado. As traduções em cache são reutilizadas. | Desenvolvimento e CI — quando texto novo ou alterado precisa de ser traduzido. |
"cache-only" | Usa apenas as traduções de .lingo/metadata.json. Falha se faltar alguma tradução. | Builds de produção — resultados determinísticos, sem chamadas a APIs externas. |
Como funciona o modo translate#
No modo translate, o Compiler verifica cada string traduzível face a .lingo/metadata.json. Se existir uma tradução em cache e o texto de origem não tiver mudado, é usada a versão em cache. Se a string for nova ou tiver sido alterada, o Compiler recorre ao fornecedor de tradução configurado para gerar uma tradução e atualizar a cache.
{
buildMode: "translate",
}Este é o modo predefinido. Funciona tanto com o pseudotradutor (para traduções simuladas instantâneas) como com fornecedores de LLM reais.
Como funciona o modo cache-only#
No modo cache-only, o Compiler lê as traduções exclusivamente de .lingo/metadata.json. Não são feitas chamadas ao LLM. Se faltar alguma string traduzível na cache, o build falha com um erro que lista as strings em falta.
.lingo/metadata.json tem de ser committed para o controlo de versões. Os builds de produção no modo cache-only dependem de este ficheiro estar presente no repositório — não basta ser gerado localmente.
{
buildMode: "cache-only",
}Este modo produz builds determinísticos — o mesmo código-fonte e a mesma cache produzem sempre o mesmo resultado. Além disso, elimina dependências de APIs externas durante os builds de produção.
workflow recomendado#
Desenvolvimento — pseudotradutor
Ative o pseudotradutor para obter feedback imediato, sem chamadas à API:
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}As pseudotraduções surgem como [!!! Welcome !!!], o que facilita a identificação de strings por traduzir e o teste do layout com diferentes comprimentos de texto.
CI — modo translate
Execute com buildMode: "translate" e um fornecedor de LLM real. O job de CI gera traduções para quaisquer strings novas ou alteradas e faz commit do .lingo/metadata.json atualizado para o repositório.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProdução — modo cache-only
Implemente com buildMode: "cache-only" para usar apenas traduções pré-geradas. Não são necessárias chaves de API no ambiente de produção.
# Production environment
LINGO_BUILD_MODE=cache-only npm run buildSubstituição por variável de ambiente#
A variável de ambiente LINGO_BUILD_MODE sobrepõe-se à opção de configuração buildMode. Isto permite usar o mesmo ficheiro de configuração em diferentes ambientes:
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run buildA variável de ambiente tem precedência sobre o valor definido no ficheiro de configuração.
Exemplos de CI#
# .github/workflows/translate.yml
name: Generate Translations
on:
push:
branches: [main]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
env:
LINGO_BUILD_MODE: translate
LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: update translations"
file_pattern: ".lingo/metadata.json"Faça sempre commit de .lingo/metadata.json para o controlo de versões. Os builds de produção no modo cache-only dependem deste ficheiro. Se estiver em falta ou incompleto, o build falhará.
