Traduzindo conteúdo¶

Como começar a traduzir¶

Se quiser contribuir com os esforços de tradução do BeeWare, você precisará de uma conta no Weblate. Crie uma nova conta se ainda não tiver uma; em seguida, informe-nos que está interessado em ajudar com as traduções.

Há duas opções para nos informar que você gostaria de ajudar com as traduções:

Se você estiver no Discord, entre no servidor BeeWare e vá para o canal #translations.
Se você não estiver no Discord, poderá criar um novo problema no repositório BeeWare.

Em ambos os casos, deixe uma mensagem com as seguintes informações:

Seu nome de usuário do Weblate
O idioma para o qual você está planejando traduzir o conteúdo

Assim que tivermos essas informações, você será adicionado à equipe.

Adição de uma nova tradução¶

Se o idioma com o qual você pretende ajudar ainda não existir, há algumas etapas adicionais necessárias para que você possa começar:

Crie o arquivo /docs/mkdocs.language-code.yml, com conteúdo específico do idioma.
Atualize o tox.ini para incluir os comandos de compilação da nova linguagem.
Atualize /docs/config.yml para incluir o idioma em extra: alternate:.

A seguir, demonstramos as alterações necessárias usando o alemão como exemplo; já existe uma tradução para o alemão; substitua as referências ao alemão, de ou outro conteúdo para o idioma que você está segmentando.

Um novo arquivo de configuração do MkDocs¶

Primeiro, crie um novo arquivo chamado mkdocs.de.yml no diretório docs, com o seguinte conteúdo:

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

Veja o que está acontecendo nesse arquivo:

Esse arquivo herda o conteúdo da configuração de config.yml.
O valor site_name é traduzido.
O valor site_url é o URL do site do projeto, seguido pelo código do idioma.
O docs_dir deve ser o código do idioma.
O valor theme: language: deve ser o código do idioma, conforme especificado pelo tema MkDocs Material. Para a maioria dos idiomas, esse será o mesmo código de idioma do docs_dir, mas para alguns (em particular idiomas com variantes de localidade como zh_CN), há diferenças.
O extra: translation_type: deve ser machine até que a tradução atinja 100% pela primeira vez, momento em que deve ser human. Ele será revertido para machine a partir de human se cair para menos de 90%.

Atualizar o `tox.ini`¶

Você precisará fazer várias alterações no arquivo tox.ini.

Você acrescentaria o seguinte:

O novo sinalizador de ambiente de código de idioma para a linha de cabeçalho que começa [testenv:docs, com o código de idioma precedido por um -, sem espaços incluídos, por exemplo, -de.
A exclusão do novo código de idioma para o primeiro comando, que começa com !lint, precedido por -!, sem espaços, por exemplo, -!de.
O código do novo idioma ao final da linha que começa com translate : build_po_translations.
O código do novo idioma ao final da linha que começa com translate : update_machine_translations
Um novo comando, começando, por exemplo, com de : build_md_translations para alemão, após os outros comandos específicos de idioma existentes que correspondem ao conteúdo desses comandos com o novo código de idioma.
O novo código de idioma ao final da linha que começa com all,serve :.

Atualizar `config.yml`¶

Adicione o idioma a config.yml para que ele apareça no seletor de idioma no cabeçalho. Localize a seção que começa com extra: e, em seguida, localize a subseção que começa com alternate:. Para o alemão, você adicionaria o seguinte:

    - name: Deutsch
      link: /de/
      lang: de

O nome do idioma deve ser traduzido para o idioma. O link deve incluir os /s.

O novo idioma agora está pronto para começar a ser traduzido.

Diretrizes de tradução¶

Depois de ter sido adicionado à equipe, é hora de fazer login no Weblate e começar a trabalhar na tradução das cadeias de caracteres.

Tom versus tradução palavra por palavra¶

É mais importante manter o tom do texto em inglês do que se esforçar para fazer uma tradução palavra por palavra. Tentamos ser amigáveis e um pouco coloquiais em nosso conteúdo; tente manter o espírito disso em suas traduções.

Se o texto em inglês contiver uma expressão idiomática forte em inglês, não se sinta obrigado a manter essa expressão se houver um análogo em seu idioma que funcione igualmente bem. Se o termo ou a frase no texto em inglês for um termo particularmente idiomático ou uma gíria, não tenha medo de nos dizer que devemos considerar fazer uma alteração. Mesmo para falantes de inglês, expressões idiomáticas e gírias podem causar dificuldades. Às vezes, precisamos alterar o texto em inglês para torná-lo mais direto para tradutores e leitores.

Devo traduzi-lo?¶

Os itens a seguir não devem ser traduzidos ou atualizados:

Comandos. Por exemplo, em "You should run `briefcase create`.", apenas "You should run" deve ser traduzido.
Namespaces, como nomes de classes, métodos ou atributos.
URLs de links. Os links padrão do Markdown devem aparecer no Weblate como [Link text]{1}, onde 1 é a posição do link na string com referência a outros links possíveis. Se a URL completa for incluída na string, como [Link text](https://example.com), a URL deve ser ignorada na tradução.
Links de referência contendo nomes de classes, métodos ou atributos. Eles devem ser deixados como estão, inclusive os backticks. Todas as partes do link de exemplo mostrado aqui não seriam traduzidas.
```
[`Class.attribute`][Class.attribute]
```
O conteúdo do link de uma referência. Por exemplo, link-content seria ignorado no seguinte:
```
[Link text][link-content]
```
Diretivas Jinja. Trata-se de qualquer conteúdo envolvido em dois pares de chaves correspondentes ou em um par correspondente de chaves simples com sinais de porcentagem em cada extremidade. Observação: a inclusão de um exemplo da sintaxe aqui faz com que o plug-in Macros tente renderizá-la; consulte a documentação do Macros para obter exemplos.
Âncoras personalizadas. Elas são encontradas após os cabeçalhos ou acima de algum conteúdo e são formatadas como { #anchor }.
Sintaxe de admoestação. No exemplo a seguir, a palavra "admonition" não deve ser traduzida. Isso vale para todos os estilos de admoestações, incluindo notas, avisos etc. Consulte a próxima seção para obter informações sobre como traduzir o restante do conteúdo.
```
/// admonition | Page Title

Content.

///
```
Backticks. Eles devem permanecer como backticks; são usados para formatar código em linha e blocos de código.
A sintaxe para incluir conteúdo externo. Trata-se de qualquer coisa na mesma linha que -8<-, ou nas linhas entre dois -8<- em linhas separadas.

Os itens a seguir devem ser traduzidos:

Texto do link. Na sintaxe de link, o texto vem antes da URL e é colocado entre colchetes, como em [Link text](URL). Os links Markdown padrão devem aparecer no Weblate como [Link text]{1}, em que 1 é a posição do link na string com referência a outros links possíveis.
Texto do link de referência. Por exemplo, Link text seria traduzido da seguinte forma:
```
[Link text][link-content]
```
Títulos e conteúdo da advertência. No exemplo da advertência anterior, "Page Title" (Título da página) e "Content" (Conteúdo) devem ser traduzidos.

Weblate¶

Usamos Weblate para a tradução de nosso conteúdo. Quando adicionamos uma nova tradução, usamos DeepL para a tradução automática, a fim de produzir uma primeira passagem nas traduções. Isso significa que, normalmente, o conteúdo que você traduzirá já está traduzido por máquina. A expectativa é que você, como tradutor, revise, edite e melhore a tradução automática existente.

O Weblate processa tudo em uma base de cadeia de caracteres por cadeia de caracteres. Ele agrupa as alterações e, a cada duas horas, enviará um commit em massa com todas as strings que foram alteradas nesse intervalo. Portanto, pode levar algumas horas para que suas alterações apareçam no site, mas você pode esperar que a atualização apareça dentro de quatro horas.

Se, após esse tempo, suas alterações ainda não tiverem aparecido, a causa provável é um erro de marcação, resultando em uma falha na compilação dos documentos para esse idioma. Qualquer problema de marcação em qualquer string impedirá que toda a tradução seja publicada. Você pode ficar de olho na página de compilação do seu idioma para ver se ela foi compilada com sucesso. O link tem um formato semelhante a este link para a página de compilação em francês https://app.readthedocs.org/projects/beewareorg/; Altere o código do idioma para o seu idioma para visualizar a página de compilação apropriada. Isso mostrará o estado da compilação mais recente do site. Se a compilação falhar, consulte o log de compilação e veja se consegue identificar a origem do problema.