Localização do site

O site do OTel usa o framework multilíngue do Hugo para dar suporte a localizações de páginas. O inglês é o idioma padrão, com o inglês americano como localização padrão (implícita). Um número crescente de outras localizações é suportado, como pode ser visto no menu suspenso de idiomas na navegação superior.

Orientação para tradução

Ao traduzir páginas do inglês, recomendamos que você siga a orientação oferecida nesta seção.

Resumo

✅ O que fazer

❌ O que NÃO fazer

IDs de cabeçalho

Para garantir que os alvos das âncoras dos cabeçalhos estejam padronizados entre as localizações, ao traduzir cabeçalhos:

• Preserve o ID explícito do cabeçalho, se ele tiver um. A sintaxe de ID de cabeçalho é escrita após o texto do cabeçalho usando sintaxe como { #some-id }.
• Caso contrário, declare explicitamente um ID de cabeçalho correspondente ao ID autogerado do cabeçalho inglês original.

Links

Não traduza referências de links. Isso vale para links externos, caminhos para páginas do site e recursos locais da seção, como imagens.

A única exceção é para links para páginas externas (como https://en.wikipedia.org) que tenham uma versão específica para sua localização. Geralmente isso significa substituir o en na URL pelo código do idioma da sua localização.

Labels de definição de links

Autores de localização podem escolher traduzir ou não labels de definições de links Markdown. Se você escolher manter o label em inglês, então siga a orientação dada nesta seção.

Por exemplo, considere o seguinte Markdown:

[Hello], world! Welcome to the [OTel website][].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

Isso seria traduzido em português como:

[Olá][hello], mundo! Bem-vindo ao [site OTel][OTel website].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

Imagens e diagramas

Não faça cópias de arquivos de imagem a menos que você localize texto na própria imagem².

Traduza texto em diagramas Mermaid.

Arquivos de inclusão

Traduza fragmentos de página encontrados nos diretórios _includes da mesma forma que você traduziria qualquer outro conteúdo de página.

Shortcodes

Alguns dos shortcodes base contêm texto em inglês que você pode precisar localizar – especialmente para aqueles contidos em layouts/_shortcodes/docs.

Se você precisar criar uma versão localizada de um shortcode, coloque-o em layouts/_shortcodes/pt, onde pt é o código do idioma da sua localização. A partir daí, use o mesmo caminho relativo do shortcode base original.

Acompanhando inconsistências em páginas localizadas

Um dos principais desafios de manter páginas localizadas é identificar quando as páginas correspondentes em inglês foram atualizadas. Esta seção explica como lidamos com isso.

O campo de front-matter default_lang_commit

Quando uma página localizada é escrita, como content/pt/<some-path>/page.md, esta tradução é baseada em um commit específico da branch main da versão correspondente em inglês da página em content/en/<some-path>/page.md. Neste repositório, toda página localizada identifica o commit da página em inglês no front matter da página localizada da seguinte forma:

---
title: Seu título de página localizada
# ...
default_lang_commit: <commit-hash-mais-recente-da-pagina-original>
---

O front matter acima estaria em content/pt/<some-path>/page.md. O hash do commit corresponderia ao commit mais recente de content/en/<some-path>/page.md da branch main.

Acompanhando mudanças nas páginas em inglês

À medida que atualizações são feitas nas páginas em inglês, você pode acompanhar as páginas localizadas correspondentes que precisam de atualização executando o seguinte comando:

$ npm run check:i18n
1       1       content/en/docs/platforms/kubernetes/_index.md - content/pt/docs/platforms/kubernetes/_index.md
...

Você pode restringir as páginas alvo a uma ou mais localizações fornecendo caminho(s) assim:

npm run check:i18n -- content/pt

Visualizando detalhes das mudanças

Para quaisquer páginas localizadas que precisem de atualização, você pode ver os detalhes do diff das páginas correspondentes em inglês usando a flag -d e fornecendo os caminhos para suas páginas localizadas, ou omitir os caminhos para ver todas. Por exemplo:

$ npm run check:i18n -- -d content/pt/docs/platforms/kubernetes
diff --git a/content/en/docs/platforms/kubernetes/_index.md b/content/en/docs/platforms/kubernetes/_index.md
index 3592df5d..c7980653 100644
--- a/content/en/docs/platforms/kubernetes/_index.md
+++ b/content/en/docs/platforms/kubernetes/_index.md
@@ -1,7 +1,7 @@
 ---
 title: OpenTelemetry with Kubernetes
 linkTitle: Kubernetes
-weight: 11
+weight: 350
 description: Using OpenTelemetry with Kubernetes
 ---

Adicionando default_lang_commit a novas páginas

Ao criar páginas para sua localização, lembre-se de adicionar default_lang_commit ao front matter da página junto com um hash de commit apropriado da branch main.

Se sua tradução de página é baseada em uma página em inglês na main em <hash>, então execute o seguinte comando para adicionar automaticamente default_lang_commit ao front matter do arquivo da sua página usando o commit <hash>. Você pode especificar HEAD como argumento se suas páginas estão agora sincronizadas com a main em HEAD. Por exemplo:

npm run check:i18n -- -n -c 1ca30b4d content/pt
npm run check:i18n -- -n -c HEAD content/pt/docs/concepts

Para listar arquivos de páginas de localização com chaves de hash faltando, execute:

npm run check:i18n -- -n

Atualizando default_lang_commit para páginas existentes

Ao atualizar suas páginas localizadas para corresponder às mudanças feitas na página correspondente em inglês, certifique-se de que você também atualize o hash do commit default_lang_commit.

Se você atualizou em lote todas as suas páginas de localização que possuíam inconsistências, é possível atualizar o hash do commit desses arquivos utilizando a flag -c seguida por um hash de commit ou ‘HEAD’ para usar main@HEAD.

npm run check:i18n -- -c <hash> <PATH-TO-YOUR-NEW-FILES>
npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>

Status de inconsistência

Execute npm run fix:i18n:status para adicionar o campo drifted_from_default no front matter das páginas localizadas que estão divergentes. Este campo será utilizado em breve para exibir um banner no topo das páginas que se desviaram da versão em inglês correspondente.

Ajuda do script

Para mais detalhes sobre o script, execute npm run check:i18n -- -h.

Novas localizações

Possui interesse em iniciar uma nova localização para o site do OTel? Entre em contato com os mantenedores para demonstrar seu interesse, por exemplo através de uma discussão no GitHub ou via canal do Slack #otel-docs-localization. Esta seção explica as etapas envolvidas na criação de uma nova localização.

1. Monte uma equipe de localização

Criar uma localização é sobre formar uma comunidade ativa e colaborativa. Para iniciar uma nova localização do site do OpenTelemetry, você precisará de:

1. Um mentor de localização que seja familiar com seu idioma, como um aprovador ativo do Glossário CNCF, ou do site do Kubernetes.
2. Pelo menos dois contribuidores interessados.

2. Início da localização: crie uma issue

Com uma equipe de localização formada (ou em processo de formação), crie uma issue com a seguinte lista de tarefas:

1. Procure o código ISO 639-1 oficial para o idioma que você quer adicionar. Vamos nos referir a este código de idioma como LANG_ID no restante desta seção. Caso tenha dúvidas sobre qual código utilizar, especialmente ao escolher uma sub-região, consulte os mantenedores.

2. Identifique os usuários do GitHub do mentor e dos possíveis contribuidores.

3. Crie uma nova issue contendo a seguinte lista de tarefas no comentário inicial:

   - [ ] Informações do idioma:
     - Código de idioma ISO 639-1: `LANG_ID`
     - Nome do idioma: ADICIONE_NOME_AQUI
   - [ ] Informações da equipe de localização:
     - [ ] Mentor da localização: @GITHUB_USERNAME1, @GITHUB_USERNAME2, ...
     - [ ] Contribuidores: @GITHUB_USERNAME1, @GITHUB_USERNAME2, ...
   - [ ] Ler a página de
         [Localização](https://opentelemetry.io/docs/contributing/localization/)
         e todas as outras páginas na seção Contribuindo
   - [ ] Localizar a página inincial do site (somente) para SEU_NOME_DO_IDIOMA e
         enviar um PR. Para mais detalhes, consulte
         [Localização da página inicial](https://opentelemetry.io/docs/contributing/localization/#homepage).
   - [ ] Mantenedores OTel:
     - [ ] Atualizar `hugo.yaml`
     - [ ] Configurar cSpell e suporte de outras ferramentas
     - [ ] Criar um label de issue para `lang:LANG_ID`
     - [ ] Criar grupo de nível de organização para aprovadores `LANG_ID`
     - [ ] Atualizar proprietários de componentes para `content/LANG_ID`
   - [ ] Criar uma issue para acompanhar a tradução do **glossário**. Adicione o
         número da issue aqui. Para mais detalhes, consulte
         [Localização do glossário](https://opentelemetry.io/docs/contributing/localization/#glossary)
   

3. Localização da página inicial

Submeta um pull request com uma tradução da página inicial do site, e nada mais, no arquivo content/LANG_ID/_index.md. Certifique-se de que os mantenedores tenham as permissões necessárias para editar seu PR, já que eles adicionarão mudanças adicionais ao seu PR que são necessárias para iniciar seu projeto de localização.

Após o merge do seu primeiro PR, os mantenedores irão configurar o rótulo (label) da issue, o grupo de nível organizacional e os responsáveis pelo componente.

4. Localização do glossário

A segunda página a ser localizada é o Glossário. Essa é uma página crítica para os leitores de conteúdo localizado, já que define termos essenciais utilizados em observabilidade e no OpenTelemetry em particular. Isso é especialmente crítico se tais termos não existem em seu idioma.

Para orientação, assista ao vídeo de apresentação de Ali Dowair no Write the Docs 2024: The art of translation: How to localize technical content.

5. Localização das páginas restantes

Com a terminologia estabelecida, você pode seguir com a localização das páginas restantes do site.

Ao submeter PRs, mantenha-os pequenos: preferencialmente limitados a um arquivo ou alguns arquivos pequenos. PRs menores são mais fáceis de revisar e normalmente são aprovados mais rapidamente.

Lista de verificação do maintainer OTel

Hugo

Atualize o arquivo hugo.yaml. Adicione entradas apropriadas para LANG_ID em:

• languages
• module.mounts. Adicione pelo menos uma entrada source-target para content. Considere adicionar entradas para páginas de fallback en apenas quando a localização tiver conteúdo suficiente.

Ortografia

Procure por dicionários cSpell disponíveis como pacotes NPM @cspell/dict-LANG_ID. Caso um dicionário não esteja disponível para seu dialeto ou região, escolha a região mais próxima.

Se nenhum dicionário estiver disponível, então pule o resto desta subseção. Caso contrário:

• Adicione o pacote NPM como dependência de desenvolvimento, por exemplo: npm install --save-dev @cspell/dict-pt-br.
• Crie .cspell/LANG_ID-words.txt como as palavras do dicionário local do site para LANG_ID.
• Em .cspell.yml, adicione entradas para:
  • import
  • dictionaryDefinitions
  • dictionaries: adicione duas entradas aqui, uma para LANG_ID e uma para LANG_ID-words.txt

Suporte de outras ferramentas

• Suporte do Prettier: se LANG_ID não for bem suportado pelo Prettier, adicione regras de ignore a .prettierignore

Orientação para aprovadores e maintainers

PRs com mudanças semânticas não devem abranger localizações

Aprovadores devem garantir que PRs fazendo mudanças semânticas em páginas de documentação não abranjam múltiplas localizações. Uma mudança semântica é aquela que impacta o significado do conteúdo da página. Nosso processo de localização de documentação garante que aprovadores de localização irão, com o tempo, revisar as edições em inglês para determinar se as mudanças são apropriadas para sua localização, e a melhor forma de incorporá-las em sua localização. Se mudanças forem necessárias, os aprovadores de localização as farão via seus próprios PRs específicos da localização.

Mudanças puramente editoriais entre localizações são OK

Atualizações de páginas puramente editoriais são mudanças que não afetam o conteúdo existente e podem abranger múltiplas localizações. Isso inclui:

• Manutenção de links: Corrigir caminhos de links quebrados quando páginas são movidas ou deletadas.
• Atualização de recursos: Atualizar links para recursos externos movidos.
• Adições direcionadas de conteúdo: Adicionar novas definições ou seções específicas em arquivos desatualizados quando não for viável atualizar o arquivo completo.

Correções de links e atualizações de recursos

Por exemplo, às vezes mudanças na documentação em inglês podem resultar em falhas de verificação de links para localizações não inglesas. Isso acontece quando páginas de documentação são movidas ou deletadas.

Em tais situações, faça as seguintes atualizações para cada página não inglesa que tem um caminho que falha na verificação de links:

• Atualize a referência do link para o novo caminho da página.
• Adicione o comentário YAML # patched ao final da linha default_lang_commit no front matter.
• Não faça outras mudanças no arquivo.
• Execute novamente npm run check:links e certifique-se de que não restam falhas de links.

Quando um link externo para um recurso movido (mas semanticamente inalterado), como um arquivo do GitHub, resulta em uma falha de verificação de link, considere:

• Remover o link quebrado do refcache
• Atualizar o link em todas as localizações usando o método descrito anteriormente nesta seção.

Adições pontuais em arquivos desatualizados

Quando for necessário adicionar conteúdo novo a um arquivo traduzido que está desatualizado em relação à versão em inglês, é possível fazer uma atualização pontual. Por exemplo: se o termo “cardinalidade” for adicionado ao glossário em inglês, você pode incluir apenas essa definição na versão localizada sem atualizar todo o arquivo.

Aqui está um exemplo do fluxo de trabalho para esta atualização direcionada:

• Adicione apenas o bloco de definição de “cardinalidade” no glossário localizado.

• Atualize o front matter adicionando # patched como um comentário YAML no final da linha.

• Não faça outras mudanças no arquivo.

• Na descrição do PR, documente as alterações:

  • O conteúdo específico adicionado (definição de “cardinalidade”)
  • Que o arquivo ainda está desatualizado em outros pontos
  • O motivo da atualização pontual (por exemplo, “Adicionar nova terminologia essencial para a documentação, sem exigir sincronização total do conteúdo do arquivo”)

  Esta abordagem permite melhorias incrementais ao conteúdo localizado, mantendo a rastreabilidade das partes que ainda precisam de atualização completa.