Cada exemplo abaixo é um repositório real com .lingo/config.json versionado e traduções já no lugar, para que você possa ver a configuração ao lado do resultado que ela gerou. A maioria são aplicações executáveis; alguns existem para mostrar apenas um formato de arquivo. Clone ou faça um fork de um deles, execute lingo link para vincular seu próprio engine e fazer o push.
Escolha primeiro a abordagem#
Há duas formas de localizar com a CLI, e é isso que define quais exemplos fazem sentido para você.
Traduza os arquivos que você já tem. Seu framework mantém as traduções no formato dele — Rails YAML, Android XML, Laravel PHP, ARB, Markdown — e a CLI traduz esses arquivos no próprio lugar. Nada no seu código muda. É assim em nove dos onze exemplos abaixo.
Escreva sem chaves. Você envolve as strings em l.text(...) onde elas aparecem, lingo extract gera para você um catálogo com chaves baseadas em hash, e não há chaves de tradução para nomeear nem manter. Isso exige uma etapa de build e um pacote em runtime, e é exatamente o que mostram os dois exemplos de app web.
Apps mobile#
| Exemplo | Formato | Por que escolher este |
|---|---|---|
| iOS | xcode-xcstrings | Um String Catalog reúne todos os idioma, então o caminho de destino corresponde ao caminho de origem |
| Android | android | values/ puro como origem, com os próprios qualificadores do Android (values-pt-rBR/) |
| Flutter | flutter | Metadados @ e placeholders ICU preservados, com @@locale reescrito por arquivo |
Apps web#
Os dois exemplos sem chaves. Ambos envolvem as strings com l.text(...) e geram o catálogo com lingo extract, então a coluna do meio mostra o nome do pacote de runtime, e não de um formato de arquivo.
| Exemplo | Pacote | Por que escolher este |
|---|---|---|
| React + Vite | @lingo.dev/react | Autoria sem chave; as declarações geradas restringem l.text() às strings extraídas |
| Next.js | @lingo.dev/react-next | Criação sem chaves com roteamento por idioma, hreflang e um seletor: Pages Router |
hreflang em produção
LingoHead monta suas URLs hreflang a partir de uma prop baseUrl que, por padrão, vem vazia, então as tags saem relativas out of the box. Mecanismos de busca esperam URLs absolutas — passe a origem do seu site (<LingoHead baseUrl="https://example.com" />) antes de confiar nelas.
Conteúdo e especificações#
| Exemplo | Formato | Por que escolher este |
|---|---|---|
| Docs em Markdown | md, mdx | Prosa por padrão, com campos de frontmatter e props de MDX incluídos sob demanda |
| Markdoc | markdoc, json | Conteúdo e strings de UI do Next.js em um único push — três entradas, cada uma com opções diferentes |
| OpenAPI | yaml-openapi | Apenas resumos e descrições; paths, IDs de operação e enums permanecem intactos |
Catálogos de frameworks#
| Exemplo | Formato | Por que escolher este |
|---|---|---|
| Rails | yaml-root-key | O idioma é a chave raiz do YAML, então a própria chave raiz é reescrita |
| Laravel | php, po | Catálogos do Laravel mais um arquivo gettext; placeholders :name preservados em ambos |
| Módulos TypeScript | typescript | Catálogos como módulos TypeScript em vez de JSON. Só o formato — nenhum app os consome |
Catálogos TypeScript precisam de um export default
O formato typescript lê um export default — export default { … }, com ou sem as const. Um export nomeado não produz conteúdo traduzível, e a execução termina copiando o código-fonte literalmente. Então, se um push indicar arquivos localizados, mas praticamente zero tokens de saída, a primeira coisa a checar é o formato do export.
Como usar um deles#
npm install -g @lingo.dev/cli
lingo login
lingo link # writes your own orgId and engineId into .lingo/config.json
lingo push --waitNenhum dos exemplos commita orgId nem engineId — isso evita que um fork faça push usando o engine de outra pessoa. lingo link preenche os dois localmente.
Se você quiser usar o GitHub App em vez da CLI
O GitHub App lê engineId do .lingo/config.json commitado no seu repositório — a organização é resolvida pela própria instalação do App, mas o engine precisa estar no arquivo. Depois de fazer o fork, execute lingo link e faça commit da configuração atualizada antes de instalar o App.
Nem todo formato tem um exemplo#
Estes onze cobrem os frameworks sobre os quais as pessoas mais perguntam, mas o CLI traduz dezoito formatos. xliff, srt, Xcode .strings e .stringsdict, yaml genérico e JSON/JSONC avulso funcionam todos sem precisar ter um repositório aqui — veja Formats para a lista completa e a configuração que cada um exige.
