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

Nova equipe de localização

Para iniciar uma nova localização para o site do OpenTelemetry, você precisa 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.

Uma vez que você estiver pronto:

1. Crie uma nova issue para compartilhar seu interesse em contribuir.

2. Adicione os nomes de usuário do GitHub do mentor e dos possíveis contribuidores.

3. 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.

4. Adicione a seguinte lista de tarefas ao comentário de abertura da sua issue:

   - [ ] 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 homepage do site para SEU_NOME_DO_IDIOMA
   - [ ] Maintainers 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`
   

5. 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 configurarão o rótulo (label) da issue, o grupo de nível organizacional e os responsáveis pelo componente.

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 como corrigir caminhos de links quebrados podem abranger localizações. Uma mudança puramente editorial é aquela que não impacta o significado do conteúdo da página.

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 no final da linha para a linha de front matter default_lang_commit.
• 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.