Traduzir conteúdo¶

Como começar a traduzir¶

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

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

Se estiver no Discord, entre no servidor BeeWare e vá para o canal #translations.
Se 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:

O seu nome de utilizador do Weblate
O idioma para o qual está a planear traduzir o conteúdo

Assim que tivermos essas informações, será adicionado à equipa.

Adicionar uma nova tradução¶

Se o idioma com o qual pretende ajudar ainda não existir, há alguns passos adicionais necessários para poder começar:

Crie o ficheiro /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 sob extra: alternate:.

O seguinte demonstra as alterações necessárias usando o alemão como exemplo; já existe uma tradução para Alemão; substitua as referências ao Alemão, de ou outro conteúdo para o idioma que está a visar.

Um novo ficheiro de configuração do MkDocs¶

Primeiro, crie um novo ficheiro 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:
  language_url: de/
  translation_type: machine
  header:
    About: Über
    Documentation: Dokumentation
    Community: Gemeinschaft
    Contributing: Mitwirken
    News: Neuigkeiten
    Sponsor: Förderer

Veja o que está a acontecer nesse ficheiro:

Este ficheiro herda o conteúdo da configuração de config.yml.
O valor de site_name é traduzido.
O valor de site_url é o URL do sítio do projeto, seguido pelo código do idioma.
O docs_dir deve ser o código do idioma.
O valor de 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 pt_BR), há diferenças.
O extra: language_url: deve ser o código do idioma, seguido por uma única barra, por exemplo, pt/ para Português.
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 de human se regressar para menos de 90%.
O conteúdo sob extra: header é a tradução dos títulos que aparecem na barra de cabeçalho. Esta definição não é necessária no site principal do BeeWare; ela só é necessária em outros sites (como o tutorial ou a documentação do projeto).

Atualizar o `tox.ini`¶

Vai precisar de fazer várias alterações no ficheiro tox.ini.

Deveria acrescentar o seguinte:

A nova bandeira 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, -pt.
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 novo código de idioma para a linha que começa com translate : build_po_translations.
O novo código de idioma para a linha que começa com translate : update_machine_translations
Um novo comando, começando com, por exemplo, de : build_md_translations para Alemão, em ordem alfabética dentro dos comandos específicos do idioma existente que correspondem ao conteúdo desses comandos, com o novo código de idioma.
O novo código de idioma para a linha que começa com all:.

Atualizar `config.yml`¶

Adicione o idioma a config.yml para que ele apareça no seletor de idioma no cabeçalho. Localize a secção que começa com extra:, e depois localize a subsecção que começa com alternate:. Para Português, adicionaria o seguinte:

- name: Português
      link: /pt/
      lang: pt

O nome do idioma deve ser traduzido para o idioma. O link deve incluir as barras /.

Executar `tox translate`¶

Agora pode executar tox -e docs-translate. Isto irá gerar um ficheiro de tradução vazio; se tiver uma conta DeepL, poderá usa-la para preencher as traduções automáticas iniciais. Se não tiver uma conta DeepL, não se preocupe — nós mesmos faremos as traduções iniciais antes de aceitar o pedido de puxar.

Diretrizes de tradução¶

Depois de ter sido adicionado à equipa, é hora de iniciar sessão no Weblate e começar a trabalhar na tradução das mensagens.

Contexto contra 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 no nosso conteúdo; tente manter o espírito disso nas suas traduções.

Se o texto em inglês conter uma expressão idiomática forte em Inglês, não se sinta obrigado a manter essa expressão se houver um análogo no 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 os faladores de Inglês, expressões idiomáticas e gírias podem causar dificuldades. Às vezes, precisamos alterar o texto em Inglês para torna-lo mais direto para tradutores e leitores.

Devo traduzir isto?¶

Os seguintes items não devem ser traduzidos nem atualizados:

Comandos. Por exemplo, em "You should run `briefcase create`.", apenas a parte "You should run" deve ser traduzida.
Espaços de nomes, tais como nomes de classes, métodos ou atributos.
URLs de atalhos. Os atalhos Standard do Markdown devem aparecer no Weblate como [Link text]{1}, em que 1 representa a posição do atalho na sequência de texto em relação a outros atalhos possíveis. Se o URL completo estiver incluído na sequência de texto, como [Link text](https://example.com/), esse URL deve ser ignorado na tradução.
Ligações de referência que contêm nomes de classes, métodos ou atributos. Devem ser deixados como estão, inclusive as aspas. Todas as partes do atalho de exemplo mostrado aqui não seriam traduzidas.
```
[`Class.attribute`][Class.attribute]
```
O conteúdo do atalho de um atalho de Referência. Por exemplo, link-content seria ignorado no seguinte:
```
[Texto do atalho][link-content]
```
Diretivas Jinja. Trata-se de qualquer conteúdo envolvido em dois pares de chavetas correspondentes ou num par correspondente de chavetas simples com sinais de percentagem em cada extremidade. Nota: O incluir de um exemplo da sintaxe aqui faz com que o plug-in Macros tente renderiza-la; veja 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 advertência. No exemplo a seguir, a palavra "admonition" não deve ser traduzida. Isso vale para todos os estilos de advertências, incluindo notas, avisos etc. Consulte a próxima secção para obter informações sobre como traduzir o restante do conteúdo.
```
/// admonition | Título da página

Conteúdo.

///
```
Aspas invertidas. Elas devem permanecer como aspas invertidas; são usadas 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 seguintes items devem ser traduzidos:

Texto do atalho. Na sintaxe de atalho, o texto vem antes da URL e é colocado entre colchetes, como em [Link text](URL). Os atalhos Standard de Markdown 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 atalho de referência. Por exemplo, Link text seria traduzido da seguinte forma:
```
[Texto do atalho][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 vai traduzir já está traduzido por máquina. A expectativa é que, como tradutor, reveja, edite e melhore a tradução automática existente.

O Weblate processa tudo numa base de palavra por palavra. Ele agrupa as alterações e, a cada duas horas, submete um bolo com todas as sequências que foram alteradas nesse intervalo. Assim, pode levar algumas horas para que as suas alterações apareçam no sítio web, mas 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 numa falha na compilação dos documentos para esse idioma. Qualquer problema de marcação em qualquer sequência vai impedir que toda a tradução seja publicada. Pode ficar atento à página de compilação do seu idioma para ver se ela foi compilada com sucesso. O atalho tem um formato semelhante a este atalho 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 ver a página de compilação apropriada. Isto vai mostrar o estado da compilação mais recente do sítio. Se a compilação falhar, consulte o relatório de compilação e veja se consegue identificar a origem do problema.