Modos de build
Alpha
O Compiler da Lingo.dev está em alpha. Ele é instável, não é recomendado para uso em produção e as APIs podem mudar entre releases.
O Compiler da Lingo.dev opera em dois modos de build que determinam se novas traduções serão geradas durante o build. Entender esses modos é essencial para configurar um pipeline confiável de desenvolvimento, CI e produção.
Os dois modos#
| Modo | Comportamento | Quando usar |
|---|---|---|
"translate" | Gera traduções ausentes chamando o provedor de LLM configurado. Traduções em cache são reutilizadas. | Desenvolvimento e CI — quando textos novos ou alterados precisam ser traduzidos. |
"cache-only" | Usa apenas as traduções de .lingo/metadata.json. Falha se alguma tradução estiver ausente. | Builds de produção — saída determinística, sem chamadas externas de API. |
Como o modo translate funciona#
No modo translate, o Compiler verifica cada string traduzível em relação a .lingo/metadata.json. Se já existir uma tradução em cache e o texto-fonte não tiver mudado, a versão em cache será usada. Se a string for nova ou tiver sido modificada, o Compiler chama o provedor de tradução configurado para gerar uma tradução e atualiza o cache.
{
buildMode: "translate",
}Este é o modo padrão. Ele funciona tanto com o pseudotradutor (para traduções fictícias instantâneas) quanto com provedores reais de LLM.
Como o modo cache-only funciona#
No modo cache-only, o Compiler lê as traduções exclusivamente de .lingo/metadata.json. Nenhuma chamada à LLM é feita. Se qualquer string traduzível estiver ausente no cache, o build falhará com um erro listando as strings ausentes.
.lingo/metadata.json precisa ser commitado no controle de versão. Os builds de produção no modo cache-only dependem de esse arquivo estar presente no repositório — não apenas de ter sido gerado localmente.
{
buildMode: "cache-only",
}Este modo produz builds determinísticos — o mesmo código-fonte e cache sempre geram a mesma saída. Ele também elimina dependências de APIs externas durante builds de produção.
workflow recomendado#
Desenvolvimento — pseudotradutor
Ative o pseudotradutor para ter feedback instantâneo, sem chamadas de API:
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}As pseudotraduções aparecem como [!!! Welcome !!!], facilitando identificar strings não traduzidas e testar o layout com diferentes comprimentos de texto.
CI — modo translate
Execute com buildMode: "translate" e um provedor real de LLM. O job de CI gera traduções para qualquer string nova ou alterada e faz commit do .lingo/metadata.json atualizado de volta no repositório.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProdução — modo cache-only
Faça o deploy com buildMode: "cache-only" para usar apenas traduções pré-geradas. Nenhuma chave de API é necessária 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 substitui a opção de configuração buildMode. Assim, você pode usar o mesmo arquivo 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 arquivo 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"Sempre faça commit de .lingo/metadata.json no controle de versão. Os builds de produção no modo cache-only dependem desse arquivo. Se ele estiver ausente ou incompleto, o build falhará.