Configuração da CLI
Defina a deteção de ficheiros de origem, as opções de tradução e os caminhos de destino em .lingo/config.json.
.lingo/config.json define os ficheiros que um projeto traduz e onde devem ficar as respetivas traduções. A CLI procura a configuração mais próxima nos diretórios ascendentes, a partir do diretório de trabalho, e usa essa raiz para resolver os caminhos relativos ao projeto. Os comandos locais de catálogo usam cwd quando não existe configuração.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "locales/en.json" }]
}Execute link para adicionar os IDs da organização e do motor de localização necessários à tradução remota. A extração pode usar as definições de i18n localmente sem esses IDs. Use JSON estrito: não são aceites comentários nem vírgulas finais.
Campos da raiz #
| Campo | Significado |
|---|---|
orgId, engineId | IDs de recursos não vazios; em conjunto, estabelecem a associação remota. |
sourceLocale | Cadeia de carateres não vazia que identifica o idioma de origem. |
targetLocales | Entradas com cadeias de carateres não vazias; durante a execução, são removidos os duplicados e a correspondência exata com o idioma de origem. |
files | Entradas de origem descritas abaixo. |
i18n.messagesPath | Diretório do catálogo para extração, verificação e limpeza; predefinição: locales. |
i18n.typesPath | Caminho da declaração para extração e verificação; predefinição: lingo.d.ts. |
github.workflows.onPushToDefaultBranch.enabled | Gatilho opcional da integração para o ramo predefinido. |
github.workflows.onPullRequest.enabled | Gatilho opcional da integração para pedidos de integração. |
github.safety.requireApproval | Definição opcional de aprovação das execuções da integração. |
As chaves desconhecidas na raiz e nas entradas de ficheiros geram avisos e são ignoradas. Um erro de escrita pode manter um valor predefinido em vigor, em vez de provocar a rejeição de todo o ficheiro.
O comando init escreve as definições de localização; link escreve os IDs de associação; unlink remove apenas esses IDs. As operações de escrita preservam as outras secções da raiz, mas init --force reconstrói as entradas de ficheiros e perde as opções avançadas. As definições do GitHub não instalam a aplicação nem fazem com que um push da CLI acione a automatização do repositório; use a configuração da integração.
Campos das entradas de ficheiros #
| Campo | Significado |
|---|---|
pattern | Um padrão de origem não vazio. |
include | Padrões de origem; têm precedência sobre pattern, mesmo quando a lista está vazia. |
exclude | Padrões excluídos desta entrada. |
format | Formato definido explicitamente, da lista de formatos suportados abaixo. |
localeFormat | Representação do caminho em bcp47, underscore ou android. |
targetPath, sourceRoot | Modelo de saída e prefixo opcional a remover para [path]. |
translateFrontmatterFields | Campos de metadados selecionados pelos processadores da família Markdown. |
translateComponentProps | Nomes de propriedades ou regras de propriedades com filtro por componente. |
lockedKeys, preservedKeys, ignoredKeys | Listas não vazias de caminhos de chaves para os processadores que as suportam. |
injectLocale | Booleano ou { "enabled": true, "key": "language" }. |
keyColumn | Apenas CSV: cabeçalho da coluna de chaves; por predefinição, a primeira célula do cabeçalho. |
lockedPatterns | Apenas para ficheiros de propriedades: as expressões regulares RE2 presentes nos valores mantêm-se sem tradução. |
Cada entrada precisa de pattern ou include; um include vazio não seleciona nada. As opções são definidas pela primeira entrada correspondente. Controlos de chaves explica a quem pertencem os valores e os limites dos formatos.
Padrões de ficheiros #
O mecanismo de correspondência suporta * dentro de um segmento e **/ entre diretórios. Use docs/en/**/* para uma subárvore recursiva; um ** isolado no final não tem o mesmo efeito. Não assuma que as chavetas ou extglob se comportam como noutra biblioteca de padrões glob.
{
"sourceLocale": "en",
"targetLocales": ["de"],
"files": [
{
"include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
"exclude": ["docs/en/private/**/*"]
}
]
}Uma exclusão aplica-se apenas à respetiva entrada; outra entrada pode continuar a incluir o ficheiro. A deteção ignora .git e node_modules, mas não tudo o que está em .gitignore. Os padrões posicionais de push restringem ainda mais a seleção à interseção com as origens configuradas e alteram o modo de planeamento. Coloque-os entre aspas na linha de comandos.
Seleção do formato #
Os formatos configurados são json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv e properties.
| Sufixo | Formato inferido |
|---|---|
.json, .jsonc | JSON ou JSONC. |
.md, .mdx, .mdoc | Markdown, MDX, Markdoc. |
.html, .htm | HTML. |
.po, .arb | Gettext, Flutter. |
.strings, .xcstrings, .stringsdict | Formato Apple correspondente. |
.ts, .mts, .cts | TypeScript. |
.srt, .xlf, .xliff, .php | SubRip, XLIFF, PHP. |
.txt | Texto simples, apenas com um padrão que termine em .txt ou com o formato txt. |
.csv | CSV, apenas com um padrão que termine em .csv ou com o formato csv. |
.properties | Ficheiros de propriedades Java, apenas quando o padrão termina no formato .properties ou properties. |
.yaml, .yml | Defina explicitamente yaml, yaml-root-key ou OpenAPI baseado em yaml. |
.xml | Defina android explicitamente; XML genérico não é suportado. |
Para OpenAPI, o identificador exato é yaml-openapi. Mesmo com a seleção explícita do formato, continua a aplicar-se a lista de sufixos suportados pela deteção. Um ficheiro .txt, .csv ou .properties só pode pertencer a uma entrada cujo padrão termine nessa extensão ou que defina o formato correspondente, txt, csv ou properties. Essa entrada seleciona apenas ficheiros com essa extensão. Os ficheiros .js, .tsx, .pot, MJML e VTT não estão configurados como ficheiros de entrada da CLI. A extração de React TSX é uma operação distinta.
A tradução de HTML atualiza o texto e os atributos selecionados diretamente no código-fonte original, preservando a marcação, os comentários e a formatação que não foram alterados. Um elemento <html> explícito recebe o idioma de destino no atributo lang; os fragmentos mantêm-se como fragmentos. Consulte HTML para saber mais sobre a seleção de texto e o comportamento da saída.
Formatos descreve o comportamento do analisador, incluindo as estruturas ignoradas e os limites de reconstrução. Os processadores partilhados do servidor não alargam esta enumeração da CLI.
Caminhos de saída #
Use um modelo explícito quando os caminhos de origem não identificarem o respetivo idioma:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [
{
"pattern": "docs/**/*.md",
"sourceRoot": "docs",
"targetPath": "i18n/[locale]/docs/[path]"
}
]
}docs/start.md passa a i18n/de/docs/start.md e i18n/fr/docs/start.md. [locale] usa a representação do idioma definida na entrada; [path] remove a raiz de origem, respeitando os limites dos segmentos. Uma raiz docs não remove parte de docsite.
Os modelos exigem [locale]; as entradas glob também exigem [path]. Estes são os únicos marcadores de posição. São rejeitados caminhos absolutos, .., raízes glob, raízes fora das entradas e saídas novamente detetadas como origens configuradas. sourceRoot sem targetPath é inválido. O comando push também verifica colisões entre saídas sem distinguir maiúsculas de minúsculas.
Os comandos push, pull e purge também têm em conta o sistema de ficheiros: se uma origem, um destino, .lingo/lock.json ou .lingo/config.json resolver para um caminho fora da raiz do projeto ou dentro de .git, por exemplo através de uma ligação simbólica, o comando termina com um erro antes de ler, escrever ou eliminar qualquer conteúdo nesse local. As ligações que permanecem dentro do projeto continuam a funcionar, mas não é feita qualquer escrita através de um destino ou Lockfile que seja, ele próprio, uma ligação. Num monorrepositório, execute os comandos a partir de uma raiz que contenha os ficheiros partilhados, em vez de criar ligações para esses ficheiros a partir de um pacote.
Sem um modelo, a derivação tenta, por esta ordem, um diretório do idioma de origem, o nome completo do ficheiro sem extensão e as estruturas das plataformas; por fim, insere um diretório de idioma e emite um aviso. Alguns exemplos: locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → um .lproj de destino e, em Android, values → recursos qualificados pelo idioma. Leia os avisos e confirme que a aplicação carrega esse destino.
XCStrings e CSV guardam todos os idiomas no ficheiro de origem e rejeitam targetPath. As saídas de vários idiomas partilham intencionalmente esse ficheiro; a sua existência não garante que todos os idiomas estejam presentes. Purge ignora o ficheiro partilhado, pelo que não pode remover entradas de idiomas individuais.
Selecionar metadados e texto de componentes #
Quando a opção é omitida, a tradução de formatos da família Markdown seleciona os campos title e description dos metadados iniciais. Uma lista vazia desativa a seleção; uma lista explícita seleciona outros campos. Os caminhos aninhados de valores escalares e listas exigem metadados iniciais que possam ser analisados; se estes estiverem malformados, a análise pode limitar-se ao nível superior.
{
"pattern": "docs/en/**/*.mdx",
"translateFrontmatterFields": ["title", "description"],
"translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}Uma cadeia de carateres seleciona uma propriedade sem filtrar por componente. Um objeto seleciona props e pode restringir os nomes dos componentes. Estas regras selecionam conteúdo literal traduzível, não o código dos componentes nem todos os atributos. Markdown, MDX e Markdoc têm comportamentos diferentes; verifique o processador ao mudar de caminhos.
Para fornecer orientações ao tradutor em JSONC, coloque @context imediatamente antes da respetiva cadeia de carateres. A saída JSONC geral mantém as marcas @orphan, mas remove os outros comentários. Por isso, os metadados @src do React exigem a política de carregamento do catálogo; não se deve assumir que o comando pull os preserva.
Nas estruturas de documentação, escolha os diretórios reais de origem e saída separadamente do encaminhamento. OpenAPI usa yaml-openapi; as raízes de idioma ao estilo Rails usam yaml-root-key; YAML genérico usa yaml. A correspondência da extensão, por si só, não basta para selecionar a semântica correta.
Idiomas #
A configuração valida cadeias de carateres não vazias, em vez de as comparar com uma enumeração exaustiva de idiomas. Use os identificadores de que o modelo e a aplicação precisam, incluindo a região ou o sistema de escrita. localeFormat controla os caminhos: bcp47 mantém os hífenes, underscore produz pt_BR e android produz formas como pt-rBR ou b+zh+Hans. O formato Android seleciona a representação Android, salvo indicação em contrário; isto também afeta a correspondência das origens.
Conclua as atualizações normais pendentes dos ficheiros de origem antes de adicionar um destino e preencher os ficheiros que lhe faltam. Adicionar um idioma explica como esta ordem mantém os idiomas existentes atualizados. Remover um destino impede a sua seleção futura sem eliminar os ficheiros existentes. Os metadados de idioma incorporados e os catálogos partilhados seguem as regras do respetivo processador. Um caminho escrito corretamente não garante a direção do texto, o encaminhamento nem a qualidade linguística.
Caminhos do catálogo #
Para extração e verificação, os valores explícitos de --out/--types têm precedência sobre as definições de i18n; na ausência de ambos, aplicam-se as predefinições. --source-locale usa en por predefinição, independentemente da definição de localização sourceLocale. Alterar messagesPath não atualiza files[]; selecione o caminho JSONC gerado para tradução.
Monorrepositórios #
Uma configuração na raiz permite partilhar idiomas e um motor de localização entre caminhos de pacotes recursivos ou explícitos. Em alternativa, as configurações por pacote permitem manter os idiomas, a configuração e os Lockfiles independentes. Execute os comandos a partir da raiz do pacote pretendido, para evitar que a deteção da configuração mais próxima selecione inesperadamente uma configuração num diretório ascendente.
Uma matriz de diretórios de CI deve preservar a saída recolhida de cada projeto e evitar operações de escrita sobrepostas. Os apontadores de execução locais no diretório pessoal dependem de raízes absolutas e não são partilhados através de um Lockfile. lingo check compara cada origem selecionada por files com o Lockfile ao nível do ficheiro; não verifica as chaves no seu interior.
Configuração da pontuação #
lingo score usa o ficheiro executável lingo.config.ts, carregado através de Jiti. Esta configuração é independente do JSON do projeto e não regista carregadores locais de formatos arbitrários. Mantenha os módulos de pontuação de confiança separados das definições remotas de localização de ficheiros.