O Ansel usa o Gettext  para traduzir todas as partes do projeto:

  • O aplicativo de software (escrito em C),
  • O site (templates do Hugo e conteúdo em Markdown),
  • A documentação/manual do usuário, inserida no site como um módulo (também templates do Hugo e conteúdo em Markdown).

Isso garante que o mesmo fluxo de trabalho possa ser usado para traduzir todos os arquivos, mas também que algumas strings traduzidas possam ser compartilhadas (por exemplo, os controles de interface traduzidos dos aplicativos podem ser inseridos diretamente na documentação).

Organização dos arquivos de tradução

O código-fonte do site, da documentação e do software contém, todos eles, uma subpasta po/ imediata, contendo:

  • um arquivo .pot que reúne todas as strings traduzíveis disponíveis em seu idioma original (em inglês),
  • vários arquivos .po que associam as strings traduzíveis em seu idioma original com a sua tradução (um idioma por arquivo).

Os arquivos de tradução são todos nomeados seguindo a convenção language-code.po. Por exemplo:

  • para o alemão,
    • a tradução do software é de.po,
    • a tradução do site é content.de.po,
    • a tradução da documentação é content.de.po,
  • para o português do Brasil,
    • a tradução do software é pt_BR.po,
    • a tradução do site é content.pt_br.po,
    • a tradução da documentação é content.pt_br.po.

Traduzindo quando você não pode usar CLI/Git

Você precisará localizar o arquivo .po relevante para o seu idioma, referente à parte do projeto que você quer traduzir:

  1. Baixe esse arquivo e abra-o com o Poedit ,
  2. Faça as correções e edições que você precisar,
  3. Adicione o seu nome em um comentário nas strings que você traduzir, se quiser receber os créditos na página :
    • As strings traduzidas automaticamente terão TRANSLATOR ChatGPT ali; assim que você verificar essas strings, remova essa linha,
    • Em seguida, adicione um comentário contendo TRANSLATOR Seu Nome em uma nova linha. Mantenha os outros colaboradores (não ChatGPT) ali, se houver.
  4. Salve o arquivo e:
    • Alternativa 1 (mais fácil para o colaborador, mais etapas para o mantenedor): deposite-o na minha nuvem privada ,
    • Alternativa 2 (mais etapas para o colaborador, mais fácil para o mantenedor): faça o commit com o Git e abra um pull request no repositório correto do Github.

Traduzindo para usuários avançados

Isso atualizará o arquivo .pot usando o código-fonte do projeto. Você precisará ter o Git instalado e o Hugo 0.146  instalado no seu computador.

  1. Clone o código-fonte do projeto relevante:
    • o software :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel.git
3$ cd ansel
    • o site :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-website.git
3$ cd ansel-website
    • a documentação :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-doc.git
3$ cd ansel-doc
    Mais tarde, você atualizará o repositório usando :
    1$ git pull
  2. Atualize o arquivo .pot e todos os arquivos .po a partir do código-fonte (esta etapa funciona da mesma forma para os 3 projetos):
    1$ sh tools/update-translations.sh
  3. Traduza o arquivo .po relevante usando o Poedit ou diretamente em um editor de texto (veja Traduzindo quando você não pode usar CLI/Git),
  4. Teste e revise a sua tradução :
    • Para o software, você precisará compilar o Ansel no seu sistema operacional. Consulte a documentação.
    • Para o site e a documentação, você pode executar :
      1sh build-modules.sh
2hugo
    Fique atento a qualquer erro crítico do po4a, especialmente quanto a caracteres \n incompatíveis, e a erros do Hugo, especialmente quanto à sintaxe dos shortcodes.
  5. Para o site e a documentação, limpe os arquivos Markdown traduzidos (gerados automaticamente pelo po4a a partir do arquivo .po) antes de fazer o commit, usando :
    1sh tools/build-translations.sh --remove
  6. Faça o commit de todos os arquivos .pot e .po e abra um pull request no repositório correspondente do Github. Nunca faça o commit de arquivos .md (Markdown) traduzidos.

Traduzindo imagens

O que se segue aplica-se apenas ao site e à documentação.

As imagens também podem ser traduzidas, por exemplo capturas de tela do aplicativo. As imagens são armazenadas na pasta assets/ se forem reutilizadas em várias páginas (assets globais); caso contrário, são armazenadas na mesma pasta do arquivo Markdown que as utiliza (assets locais). Sejam globais ou locais, o processo de tradução é o mesmo, apenas a pasta base muda.

Se, por exemplo, você quiser traduzir o assets/screenshot.jpg para o idioma LANG (que é o código ISO do idioma, como de, nl, pt_br, zn_cn, etc.):

  1. adicione e faça o commit de um novo arquivo de imagem assets/screenshot.LANG.jpg no repositório Git da documentação ou do site,
  2. no content.LANG.po, localize a entrada contendo a tag Markdown da imagem original, que será algo como ![alt text](screenshot.jpg),
  3. traduza a tag Markdown substituindo a URL da imagem, como ![texto alt traduzido](screenshot.LANG.jpg,
  4. salve e faça o commit do arquivo content.LANG.po,
  5. crie um pull request no repositório do site do Ansel ou da documentação do Ansel.

Ferramentas automáticas e scripts auxiliares

Inicializar a tradução da documentação com a do software

Como a documentação e o software compartilham as mesmas strings para os controles da interface, você pode inicializar de forma preguiçosa as strings da documentação a partir das do software, se elas coincidirem exatamente (inclusive na capitalização). Isso exige um interpretador Python e o pacote regex (instale com pip install -U regex). A partir do código-fonte da documentação, você pode chamar :

1$ python tools/merge-translations.py path/to/software path/to/doc

Traduzir automaticamente a documentação e o site com o ChatGPT

O ChatGPT-4o faz um trabalho bastante razoável ao traduzir texto formatado em Markdown a partir do inglês, embora não em todos os idiomas. Você precisará de uma chave de API privada para armazenar na pasta da documentação ou do site em um arquivo .chatgpt.api_key. Além disso, as chamadas à API do ChatGPT não são gratuitas, e o pagamento mínimo de 5 US$ deverá render, aproximadamente, o site totalmente traduzido para 4 idiomas.

O script tudo-em-um pode ser chamado usando :

1$ sh auto-translate.sh LANG

onde LANG é o código do idioma de destino (de, fr, pt_br, etc.). Isso processará a tradução em lotes de 90 a 120 strings para respeitar as limitações e os limiares da API do ChatGPT. Isso irá :

  • analisar o arquivo original po/content.LANG.po e exportar o lote a traduzir para um arquivo temporário po/content.LANG.txt,
  • enviar o arquivo po/content.LANG.txt ao ChatGPT e obter a resposta em po/content.LANG.generated.txt
  • corrigir as inconsistências de formatação mais comuns que o ChatGPT pode introduzir e injetar as traduções de volta em po/content.LANG.po,
  • construir os arquivos Markdown traduzidos (seguindo a convenção de nomenclatura page.LANG.md),
  • construir o site com o Hugo.

Se todas essas etapas forem concluídas sem erro, então você está pronto para executar o script novamente e processar o próximo lote até a conclusão. Se erros forem exibidos, você precisará corrigi-los. Executamos apenas um lote a cada chamada para dar ao usuário a oportunidade de encontrar erros enquanto não há muitas alterações a inspecionar.

Erros comuns:

  • nada será traduzido : verifique a resposta do ChatGPT dentro de po/content.LANG.generated.txt, às vezes ele é incapaz de entender a sua tarefa. Você pode tentar de novo, às vezes funciona na 3ª chamada. Mas, muitas vezes, não há o que fazer e alguns idiomas/strings não podem ser traduzidos de forma alguma.
  • ao construir o site com o Hugo, algum shortcode não pode ser encontrado. Isso ocorre porque os shortcodes são declarados assim : {{< shortcode_name >}}. Às vezes, o ChatGPT tentará traduzir shortcode_name e o shortcode deixará de funcionar. A solução é trazer de volta o nome em inglês do shortcode e de seus atributos,
  • o mesmo acontece com os gráficos Mermaid , o ChatGPT pode tentar traduzir comandos e propriedades que não deveriam ser traduzidos,
  • as strings originais terminam com o caractere de nova linha \n e as strings traduzidas não (ou vice-versa). O script tenta higienizar isso, mas alguns casos extremos não são tratados. As strings originais msgid e a sua tradução msgstr no arquivo .po devem ter o mesmo número de caracteres \n no mesmo lugar,
  • aspas duplas escapadas de forma incorreta : as strings Gettext msgid e msgstr devem ser delimitadas por aspas duplas não escapadas " em cada extremidade da string. Qualquer outra aspa dupla, dentro da string Gettext, deve ser escapada usando \".

A melhor maneira de corrigir erros é abrir o arquivo .po relevante em um editor de texto. Se você não conseguir encontrar o erro e resolvê-lo, pode tentar abrir o arquivo no Poedit, mas, ao salvar, ele geralmente apagará completamente as strings problemáticas sem corrigi-las, então a tradução precisará ser recomeçada do zero.

Construir os arquivos Markdown traduzidos

Para o site e a documentação, o Hugo  trata as traduções de qualquer página new_page.md usando a convenção de nomenclatura new_page.LANG.md, onde LANG é o código do idioma. O Hugo suporta nativamente a escrita manual desses arquivos traduzidos na mesma pasta do original; no entanto, aqui nós os geramos usando o arquivo de tradução .po e o programa po4a. Os scripts build-modules.sh e tools/auto-translate.sh cuidam disso internamente, mas você pode querer gerar esses arquivos manualmente :

  1. Atualize os arquivos .pot e .po com o código-fonte :
    1$ sh tools/update-translations.sh
  2. Crie os arquivos .md traduzidos :
    1$ sh tools/build-translations.sh --add
  3. Limpe os arquivos .md traduzidos :
    1$ sh tools/build-translations.sh --remove

É importante nunca fazer o commit dos arquivos .md traduzidos com o Git, pois eles são regenerados apenas a partir desse script ao construir o site. Isso é apenas para a higiene do repositório, não há desvantagem técnica. Limpar os arquivos .md traduzidos antes de fazer o commit garante que não haja erros.

Perdido na tradução ?

Se você tiver problemas ou dúvidas, sinta-se à vontade para perguntar no canal dedicado do Matrix para tradutores .

Notas para os tradutores

Política sobre maiúsculas

O projeto darktable fez questão de colocar tudo em minúsculas, o que torna a interface difícil de ler, especialmente para dicas de ferramentas com várias frases. As maiúsculas ancoram visualmente o início das frases e outros textos importantes, como botões, controles etc. Não é por acaso que todos os idiomas convergiram para o uso delas (embora o alemão tenha a sua maneira particular de colocá-las por toda parte), elas ajudam na legibilidade, quer você goste da sua estética ou não.

O código-fonte do Ansel reutiliza a maioria dos rótulos do darktable e adiciona uma maiúscula inicial na maioria dos lugares onde ela é necessária (cabeçalhos de módulos, botões). Isso é feito por um trecho de código que usa a função C g_unichar_toupper() da Glib do Gtk, de modo que o texto original em inglês permaneça em minúsculas para manter a compatibilidade com as traduções.

Essa correção programática funciona para caracteres não acentuados, não importa o idioma usado (strings padrão em inglês, ou traduções). No entanto, ela não funciona para caracteres acentuados iniciais, que não serão capitalizados. Nesse caso, pede-se aos tradutores que forcem a sua tradução a usar caracteres acentuados iniciais capitalizados sempre que forem gramaticalmente corretos em seu idioma.

Rótulos novos ou rótulos antigos alterados recentemente (que quebrariam as traduções de qualquer forma) receberão maiúsculas iniciais de agora em diante, no código-fonte (versão em inglês), então isso deverá ser corrigido progressivamente.

Traduzindo termos técnicos

Termos técnicos relacionados à teoria das cores e à colorimetria precisam ser traduzidos com exatidão a partir do inglês, com cuidado redobrado porque esses termos também podem existir na linguagem comum (ou seja, não técnica), mas com um significado diferente. A Comissão Eletrotécnica Internacional  disponibiliza um mecanismo de busca onde você pode pesquisar os termos técnicos em inglês e obter as traduções precisas em diferentes idiomas, incluindo os principais europeus, bem como o árabe e o chinês.

Notes aux traducteurs francophones

La traduction de darktable comporte des bizarreries incompréhensibles pour quiconque utilise un ordinateur de bureau depuis plus de 10 ans. Voici une liste rapide des erreurs à corriger:

  • “set” est traduit “positionné” mais sa traduction correcte est “réglé”. C’est illogique car “settings” est correctement traduit “réglages”. Dans Ansel, on ne positionne que des masques (ou leurs nœuds de contrôle) dans le plan 2D. Le reste, ce sont des réglages.
  • “reset” est traduit “repositionné” mais sa traduction correcte est “réinitialiser”.
  • En anglais, un grand nombre de verbes ont la même graphie pour leur infinitif et leur participe-passé, voire même existent comme substantif (“set”, dans l’exemple ci-dessus, peut être traduit “réglé” ou “régler” ou comme “ensemble” sous sa forme substantivée). Si une action (pas encore effectuée) est requise, l’infinitif doit être utilisé en français. Si une action est déjà effectuée, c’est le participe-passé qui doit être employé. Les choses se corsent pour les substantifs car l’anglais ne requiert pas toujours de déterminant devant, il faut donc le déduire du contexte. À surveiller : “click” (cliquer ou clic), “type” (type ou entrer/taper), etc.
Translated from English by : Claude. In case of conflict, inconsistency or error, the English version shall prevail.