> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/pt-br/contributing/translating.md). # Traduzindo o MyIP Leve o MyIP para o seu idioma: um comando gera o pacote de locale, uma tradução parcial é um ótimo primeiro pull request. O MyIP disponibiliza sua interface em vários idiomas — o seletor de idioma no app é a lista oficial e sempre atualizada. Adicionar o próximo é um **pacote de localidade mais uma linha no registro**. Você não precisa saber Vue, não precisa tocar em um componente e não precisa traduzir tudo antes de abrir uma pull request. {% hint style="success" %} **Resposta rápida:** faça um fork, crie uma branch a partir de `dev`, rode `pnpm i18n-new `, preencha quantas strings quiser, rode `pnpm test`, abra a pull request. Tudo o que você deixar em branco volta para o inglês. {% endhint %} Strings não traduzidas permanecem no seu pacote como `""` em vez de desaparecer. É isso que mantém uma pull request de tradução legível — cada linha do diff é uma `""` virando uma frase — e é isso que permite que um pacote com cem strings seja realmente útil no primeiro dia e cresça ao longo de várias pull requests. ## Do que um idioma é feito Quatro arquivos carregam o texto visível ao usuário. Só o primeiro é obrigatório. | Conjunto de dados | Arquivo | Tamanho | Obrigatório? | | --------------------------- | ------------------------------------------------- | ------------------------- | ---------------------------------------------------------------- | | **Pacote principal** | `frontend/locales/.json` | \~1.150 chaves | **Sim** — todas as chaves presentes, os valores podem ficar `""` | | Política de privacidade | `frontend/locales/privacy/.json` | \~50 chaves | Não — mas ou tudo ou nada | | Checklist de cibersegurança | `frontend/locales/security-checklist/.json` | \~1.080 chaves, 258 itens | Não — mas ou tudo ou nada | | Notas de versão | `frontend/data/changelog.json` | 163 entradas | Não — novos idiomas são isentos | `en.json` é a referência para todos eles. Uma tradução pode ficar atrás do inglês; nunca pode contradizê-lo. {% hint style="warning" %} **Os dois conjuntos de dados opcionais são entregues completos ou não são entregues.** Cada um é carregado como um único arquivo, sem fallback por chave dentro dele, então um arquivo pela metade renderiza uma página meio em inglês. A suíte de testes rejeita um `""` em qualquer um dos dois — conclua o arquivo de uma vez, ou deixe-o de fora. {% endhint %} ## O fluxo {% stepper %} {% step %} ### Faça fork e crie branch a partir de `dev` A mesma disciplina de branch de qualquer outra contribuição — veja [Como Contribuir](/developer/pt-br/contributing/how-to-contribute.md). ```bash git clone https://github.com//MyIP.git cd MyIP git checkout dev git checkout -b i18n/es-mx pnpm install ``` {% endstep %} {% step %} ### Crie a estrutura do idioma Um comando gera os dois arquivos que um idioma precisa. ```bash pnpm i18n-new es-MX ``` Ele cria `frontend/locales/es-MX.json` com **cada chave `en.json` que ele tem e cada valor `""`**, e acrescenta uma linha em `common/locale-registry.js` com `status: 'beta'`. Leia essa linha do registro antes de seguir em frente. O script adivinha `nativeName`, `flag` e `apiTag`, e pode errar — veja [A linha do registro](#the-registry-line). {% endstep %} {% step %} ### Traduza o quanto quiser Abra seu pacote e preencha os valores. Começar apenas com as seções `page` e `nav` é uma primeira pull request perfeitamente boa. **Deixe as chaves que você pular no lugar com seus `""`.** Apagá-las faz a suíte de testes falhar, e mantê-las é justamente o ponto: o relatório de progresso pode contar o que ainda falta, e um revisor consegue ver de relance quais strings você realmente escreveu. {% endstep %} {% step %} ### Confira seu trabalho ```bash pnpm test # a barreira difícil — precisa ficar verde pnpm i18n-status # relatório de progresso — nunca falha, só diz em que ponto você está pnpm dev # depois escolha seu idioma em Preferências ``` `?hl=` também seleciona um idioma, mas só antes de você salvar um em Preferências — uma preferência salva tem prioridade sobre o parâmetro de consulta. {% endstep %} {% step %} ### Abra a pull request contra `dev` Diga quais seções você cobriu e quais deixou para depois. Não há por que se desculpar por um pacote parcial. {% endstep %} {% endstepper %} Nenhuma mudança no backend, nenhuma configuração de build, nenhuma edição de componente. O seletor de idioma, o `` atributo, a cadeia de fallback e o carregamento preguiçoso do seu pacote são todos derivados dessa única linha do registro. ## Nomeando seu código de idioma O código é tanto o código da interface quanto o nome do seu arquivo JSON, então na prática ele é permanente depois de publicado. * **A variante padrão de um idioma usa o código simples.** `zh` é chinês simplificado; `pt` seria português europeu. * **Variantes que chegam depois usam o código regional completo:** `zh-TW`, `pt-BR`, `es-MX`. * Se o idioma base já estiver registrado, use o código regional — assim seu pacote herda o idioma base como fallback. ## A linha do registro `pnpm i18n-new` escreve isso para você. É isso que você deve conferir. {% code title="common/locale-registry.js" %} ```js { code: 'es-MX', nativeName: 'Español (México)', flag: 'mx', apiTag: 'es', htmlLang: 'es-MX', status: 'beta' }, ``` {% endcode %} | Coluna | O que colocar nela | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | O código da interface **e** o nome do seu arquivo JSON. Veja a regra de nomenclatura acima. | | `nativeName` | O nome do idioma como seus próprios falantes o escrevem — `Français`, não `French`. | | `flag` | Um [circle-flags](https://github.com/HatScripts/circle-flags) código de duas letras em minúsculas para o ícone do seletor. | | `apiTag` | A tag enviada às fontes de dados upstream. Veja abaixo. | | `htmlLang` | A tag BCP-47 escrita em ``. Seja preciso quando o script importar: `zh` declara `zh-CN` para que os glifos Han continuem em Simplificado em sistemas japoneses. | | `status` | `'beta'` para um idioma novo. Os mantenedores mudam para `'full'` — veja [De beta para full](#from-beta-to-full). | A ordem do registro também é a ordem em que o seletor de idioma é renderizado, então coloque sua entrada onde ela faça mais sentido, em vez de sempre no final. ### Selecionando `apiTag` Nomes de lugares — cidades, regiões — vêm de fontes de dados IP upstream, que localizam para um conjunto fixo de tags: `en`, `de`, `es`, `fr`, `ja`, `pt-BR`, `ru`, `zh-CN`. Coloque nelas a mais próxima disso em `apiTag`. Se nenhuma ficar próxima, repita apenas o seu próprio código; os nomes de lugares serão exibidos em inglês, o que é esperado e não é bug. Os nomes de países não são afetados — eles vêm dos próprios dados `Intl` do navegador e são localizados automaticamente para qualquer idioma. Datas e horas também. ## O que os visitantes veem para chaves que você ainda não traduziu Uma string não traduzida — uma `""`, ou uma chave que não está lá — percorre uma cadeia: **seu idioma → o idioma base dele, se registrado → inglês**. * `fr` → `en` * `zh-TW` → `zh` → `en` A cadeia se aplica por chave no pacote principal e por entrada nas notas de versão. A política de privacidade e o checklist percorrem a mesma cadeia, mas um arquivo inteiro por vez. O app nunca renderiza um vazio nem um caminho de chave cru, e não registra avisos: um `beta` pacote incompleto é um estado suportado, não um erro. No seletor de idioma, um `beta` idioma traz um pequeno **Beta** selo — de propósito a palavra em inglês, em todos os idiomas. Os valores que você deixar vazios são removidos na hora do build, então não custam nada no bundle final. ## Os conjuntos de dados opcionais Quando você estiver pronto para fazer um de uma vez só, crie a estrutura da mesma forma: ```bash pnpm i18n-new es-MX --privacy --checklist # qualquer flag, ou as duas ``` Ambos exigem que o idioma já esteja registrado, então rode o comando simples `pnpm i18n-new ` primeiro. * **A política de privacidade** é curta. Traduza de uma vez só, ou deixe-a de fora. * **O checklist** é longo — 258 itens. Mostrar o checklist completo em inglês é melhor do que mostrar lacunas, então deixe o arquivo de fora até ele estar pronto. O esqueleto dele mantém `slug` e `priority` preenchidos: isso é dado — destinos de links e prioridades de selos — não texto, e traduzi-los faz a verificação falhar. Até todo outro valor em um arquivo opcional criado a partir da estrutura estar preenchido, `pnpm test` continua vermelho. Termine o arquivo antes de commitar, ou apague-o novamente. ## O que `pnpm test` impõe `tests/locale-packs.test.js` é a barreira. Medido em relação ao inglês, seu pacote deve: * **Ter exatamente as chaves do inglês** — nem mais (um caminho digitado errado é a causa mais comum), nem menos (`pnpm i18n-sync` recoloca qualquer uma que você tenha removido). As que não forem traduzidas permanecem como `""`. * **Não usar nenhum marcador que o inglês não forneça.** `{count}`, `{name}` e semelhantes precisam ser um subconjunto do que a string em inglês usa. Mantenha-os escritos exatamente como estão e mova-os pela frase conforme a sua gramática precisar. Valores vazios são ignorados. * **Mantenha `slug` e `priority` sem tradução** no checklist de segurança. * **Não conter `""` nos dois arquivos opcionais.** * **Traduzir tudo, se o idioma for `full`.** Uma `""` deixada em um `full` pacote principal de uma localidade faz a build falhar, e os três arquivos precisam estar presentes. `beta` as localidades podem deixar quantos `""` quiserem — no pacote principal. `tests/locale-registry.test.js` verifica a estrutura da sua linha de registro, e `tests/changelog.test.js` só exige histórico de notas de versão para idiomas `full` completos. Mais sobre a suíte em [Testes](/developer/pt-br/development/testing.md). ## O que `pnpm i18n-status` mostra Por idioma e por conjunto de dados: a porcentagem traduzida e as próximas chaves a fazer. Também conta valores que são byte a byte idênticos ao inglês — às vezes correto (`MTR`, nomes de produto), às vezes um copia e cola que nunca foi traduzido. É um relatório, nunca uma barreira. ```bash pnpm i18n-status --locale es-MX --limit 30 ``` ## Quando o inglês muda sob você Novas chaves entram em `en.json` o tempo todo. Realinhe cada pacote com um comando: ```bash pnpm i18n-sync ``` Ele adiciona as novas chaves do inglês ao seu pacote principal como `""`, remove as que o inglês não tem mais e coloca tudo de volta na ordem do inglês. Rode isso sempre que `pnpm test` informar chaves ausentes, e depois de um rebase. **Ele nunca sobrescreve uma tradução.** Para a política de privacidade e o checklist, ele apenas *informa* o que mudou — escrever `""` neles faria a barreira falhar por você. Traduza as novas chaves, ou remova o arquivo. ## De beta para full Uma `full` um idioma é aquele em que toda alteração de texto futura é obrigatória, então a promoção é uma decisão dos mantenedores, tomada quando o idioma está realmente completo: * Pacote principal, política de privacidade e checklist de segurança todos com 100% em relação a `en` — nem uma única `""` restando, o que `pnpm i18n-status` vai confirmar. * Histórico das notas de versão reconstituído — todas as 163 entradas em `frontend/data/changelog.json`. * um histórico suficiente para que mudanças de texto continuem entrando no idioma. Quando `status` passa para `'full'`, as especificações de localidade e changelog começam a falhar em qualquer lacuna, e esse é exatamente o objetivo. Até lá não há pressão: um `beta` idioma nunca quebra a build. ## Melhorando um idioma existente Correções e versões melhoradas de frases para os idiomas que o MyIP já oferece são tão bem-vindas quanto novos idiomas — edite o JSON e abra a pull request. Duas coisas para ter em mente: * **Prefira uma formulação natural em vez de tradução literal.** Esta é uma ferramenta de rede, e a terminologia que a maioria dos usuários conhece costuma ser o termo em inglês. * **Preste atenção ao texto de placeholder nos campos de entrada.** Os campos de texto livre evitam de propósito as palavras "address / 地址 / adresse / adresi" — o QuickType do iOS usa isso como gatilho e oferece preencher automaticamente um endereço postal em um campo de IP. Ao traduzir um placeholder, escolha uma formulação que também evite o equivalente da sua língua. ## Limites conhecidos Coisas que vão parecer "não traduzidas" não importa o quão completo esteja o seu pacote. Nenhuma delas é bug, e nenhuma bloqueia uma pull request. | O que | Por quê | | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Nomes de lugares (cidade, região) | Eles vêm de fontes de dados IP upstream, que só publicam `de`, `en`, `es`, `fr`, `ja`, `pt-BR`, `ru`, `zh-CN`. Outros idiomas recebem nomes de lugares em inglês ao lado de uma interface totalmente traduzida. | | A tela de carregamento antes de o app aparecer | Ela carrega seu próprio pequeno conjunto de strings em `index.html` e é executada antes de o bundle do app existir. `beta` os idiomas ficam em inglês ali; os mantenedores cuidam disso no momento da promoção. | | Registros Whois, respostas de DNS, nomes de organização ASN, texto de incidentes do status do serviço | Isso é dado upstream, não texto da interface. Ele chega no idioma em que a fonte o publica. | | Estas páginas de documentação | O site que você está lendo é um repositório separado, publicado em inglês e traduzido automaticamente pelo GitBook. | | Traduções do README | Um esforço separado. Várias traduções do README são mantidas no repositório junto com a versão em inglês, e traduções da comunidade em qualquer outro idioma são bem-vindas; veja [`CONTRIBUTING.md`](https://github.com/jason5ng32/MyIP/blob/main/CONTRIBUTING.md). | O backend também não precisa mudar para um idioma novo. Ele resolve qualquer tag que a interface envie para a mais próxima que suas fontes de dados realmente tenham, então uma pull request de tradução nunca toca no código do backend. ## Planejando algo grande? Abra uma issue e diga isso antes de começar. Isso evita que duas pessoas traduzam mil chaves iguais em paralelo, e um mantenedor pode dizer se mais alguém já está trabalhando no idioma. Veja [Reportando problemas](/developer/pt-br/contributing/reporting-issues.md). ## Ainda travado? * [`TRANSLATING.md`](https://github.com/jason5ng32/MyIP/blob/main/TRANSLATING.md) — a referência oficial, mantida ao lado do código. Esta página é o caminho guiado; aquele arquivo é o livro de regras, e ele prevalece em qualquer detalhe que tenha divergido. * [i18n](/developer/pt-br/development/i18n.md) — como o sistema de tradução funciona internamente: `t()`, carregamento preguiçoso, subpacotes. * [Como Contribuir](/developer/pt-br/contributing/how-to-contribute.md) — regras de fork, branch, pull request e mensagem de commit. * [Ambiente de desenvolvimento](/developer/pt-br/development/dev-environment.md) — colocando `pnpm dev` para rodar de fato. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/pt-br/contributing/translating.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.