Capítulo 9. Traduções PO

9.1. Introdução

O GNU gettext oferece aos tradutores uma maneira fácil de criar e manter traduções de documentos. Sequências traduzíveis são extraídas do documento original em um arquivo PO (Portable Object). Versões traduzidas das strings são inseridas com um editor separado. As strings podem ser usadas diretamente ou incorporadas em uma versão traduzida completa do documento original.

9.2. Introdução

Supõe-se que o procedimento mostrado no Quick Start já tenha sido executado. A opção TRANSLATOR é necessária e já está ativada por padrão no port textproc/docproj.

Este exemplo mostra a criação de uma tradução em Espanhol do pequeno artigo Leap Seconds.

Procedimento. Instale um Editor PO
  1. É necessário um editor PO para editar os arquivos de tradução. Este exemplo utiliza o editors/poedit.

    # pkg install poedit
Procedimento. Configuração Inicial

Quando uma nova tradução é criada pela primeira vez, a estrutura do diretório e o Makefile devem ser criados ou copiados do original em Inglês:

  1. Crie um diretório para a nova tradução. O código fonte do artigo em Inglês está em ~/doc/documentation/content/en/articles/leap-seconds/. A tradução em Espanhol estará em ~/doc/documentation/content/es/articles/leap-seconds/. O caminho é o mesmo, exceto pelo nome do diretório de idiomas.

    % mkdir ~/doc/documentation/content/es/articles/leap-seconds
  2. Copie o _index.adoc do documento original para o diretório de tradução:

    % cp ~/doc/documentation/content/en/articles/leap-seconds/_index.adoc \
      ~/doc/documentation/content/es/articles/leap-seconds/
Procedimento. Tradução

A tradução de um documento consiste em duas etapas: extrair strings traduzíveis do documento original e inserir as traduções dessas strings. Essas etapas são repetidas até que o tradutor sinta que o documento foi traduzido o suficiente para produzir um documento traduzido que seja utilizável.

  1. Extraia as strings traduzíveis da versão original em Inglês para um arquivo PO:

    % cd ~/doc
    % po4a-gettextize \
      --format asciidoc \
      --option compat=asciidoctor \
      --option yfm_keys=title,part,description \
      --master "documentation/content/en/articles/leap-seconds/_index.adoc" \
      --master-charset "UTF-8" \
      --copyright-holder "The FreeBSD Project" \
      --package-name "FreeBSD Documentation" \
      --po "documentation/content/es/articles/leap-seconds/_index.po"
  2. Use um editor PO para inserir as traduções no arquivo PO. Existem vários editores diferentes disponíveis. O poedit do editors/poedit é mostrado aqui.

    % poedit documentation/content/es/articles/leap-seconds/_index.po
Procedimento. Gerando um Documento Traduzido
  1. Gere o documento traduzido:

    % cd ~/doc
    % po4a-translate \
      --format asciidoc \
      --option compat=asciidoctor \
      --option yfm_keys=title,part,description \
      --master "documentation/content/en/articles/leap-seconds/_index.adoc" \
      --master-charset "UTF-8" \
      --po "documentation/content/es/articles/leap-seconds/_index.po" \
      --localized "documentation/content/es/articles/leap-seconds/_index.adoc" \
      --localized-charset "UTF-8" \
      --keep 0

    O nome do documento gerado corresponde ao nome do original em Inglês, geralmente _index.adoc.

  2. Verifique o arquivo gerado renderizando-o para HTML e exibindo-o com um navegador web:

    % cd ~/doc/documentation
    % make

9.3. Criando Novas Traduções

O primeiro passo para criar um novo documento traduzido é localizar ou criar um diretório para mantê-lo. O FreeBSD coloca documentos traduzidos em um subdiretório nomeado para seu idioma e região no formato lang . lang é um código minúsculo de dois caracteres.

Tabela 1. Nomes de Idioma
IdiomaRegiãoNome do Diretório da Tradução

English

United States

en

Bengali

Bangladesh

bn-bd

Danish

Denmark

da

German

Germany

de

Greek

Greece

el

Spanish

Spain

es

French

France

fr

Hungarian

Hungary

hu

Italian

Italy

it

Japanese

Japan

ja

Korean

Korea

ko

Mongolian

Mongolia

mn

Dutch

Netherlands

nl

Polish

Poland

pl

Portuguese

Brazil

pt-br

Russian

Russia

ru

Turkish

Turkey

tr

Chinese

China

zh-cn

Chinese

Taiwan

zh-tw

As traduções estão em subdiretórios do diretório principal da documentação, aqui assumido como ~/doc/documentation/ como apresentado na Introdução. Por exemplo, as traduções em Alemão estão localizadas em ~/doc/documentation/content/de/ e as traduções em Francês estão em ~/doc/documentation/content/fr/.

Cada diretório de idiomas contém subdiretórios separados para os tipos de documentos, geralmente articles/ e books/.

A combinação desses nomes de diretórios fornece o caminho completo para um artigo ou livro. Por exemplo, a tradução Francesa do artigo NanoBSD está em ~/doc/documentation/content/fr/articles/nanobsd/, e a tradução em Mongol do manual está em ~/doc/documentation/content/mn/books/handbook/.

Um novo diretório de idioma deve ser criado ao traduzir um documento para um novo idioma. Se o diretório de idiomas já existir, somente um subdiretório no diretório articles/ ou books/ será necessário.

Exemplo 1. Criando uma Tradução em Espanhol do Porter’s Handbook

Crie uma nova tradução em Espanhol do Porter’s Handbook. O original é um livro em ~/doc/documentation/content/en/books/porters-handbook/.

  1. O diretório de livros em Espanhol ~/doc/documentation/content/es/books/ já existe, portanto, apenas um novo subdiretório para o Porter’s Handbook é necessário:

    % cd ~/doc/documentation/content/es/books
    % mkdir porters-handbook
  2. Copie o conteúdo do livro original:

    % cd porters-handbook
    % cp -R ~/doc/documentation/content/en/books/porters-handbook/* .

    Agora a estrutura do documento está pronta para o tradutor começar a tradução com o poedit.

9.4. Traduzindo

O sistema gettext reduz bastante o número de itens que devem ser rastreados por um tradutor. As strings a serem traduzidas são extraídas do documento original em um arquivo PO. Em seguida, um editor PO é usado para inserir as traduções de cada string.

O sistema de tradução PO do FreeBSD não sobrescreve os arquivos PO, portanto a etapa de extração pode ser executada a qualquer momento para atualizar o arquivo PO.

Um editor PO é usado para editar o arquivo. editors/poedit é usado nestes exemplos porque é simples e tem requisitos mínimos. Outros editores PO oferecem recursos para facilitar o trabalho de tradução. A Coleção de Ports oferece vários desses editores, incluindo o devel/gtranslator.

É importante preservar o arquivo PO. Ele contém todo o trabalho que os tradutores fizeram.

Exemplo 2. Traduzindo o Porter’s Handbook para o Espanhol
  1. Mude para o diretório base e atualize todos os arquivos PO.

    % cd ~/doc
    % po4a-gettextize \
      --format asciidoc \
      --option compat=asciidoctor \
      --option yfm_keys=title,part,description \
      --master "documentation/content/en/books/porters-handbook/_index.adoc" \
      --master-charset "UTF-8" \
      --copyright-holder "The FreeBSD Project" \
      --package-name "FreeBSD Documentation" \
      --po "documentation/content/es/books/porters-handbook/_index.po"
  2. Realize as traduções usando um editor de PO:

    % poedit documentation/content/es/books/porters-handbook/_index.po

Essas etapas são necessárias para todos os arquivos .adoc, exceto chapters-order.adoc e toc-*.adoc.

9.5. Dicas para Tradutores

9.5.1. Preservando macros AsciiDoc

Preserve as macros AsciiDoc que são mostradas no original em Inglês.

Exemplo 3. Preservando macros AsciiDoc

Inglês original:

msgid ""
"This example shows the creation of a Spanish translation of the short "
"extref:{leap-seconds}[Leap Seconds] article."

Tradução para o Espanhol:

msgid ""
"Este ejemplo muestra la creación de un artículo con poco contenido como el artículo "
"extref:{leap-seconds}[Leap Seconds]."

9.5.2. Preservando Espaços

Preserve os espaços existentes no início e no final das strings a serem traduzidas. A versão traduzida também deve ter esses espaços.

9.5.3. Tags

O conteúdo de algumas tags devem ser copiadas igualmente, sem realizar tradução:

9.6. Compilando um Documento Traduzido

Uma versão traduzida do documento original pode ser criada a qualquer momento. Quaisquer porções não traduzidas do original serão incluídas em Inglês no documento resultante. A maioria dos editores PO tem um indicador que mostra quanto da tradução foi realizada. Isso torna mais fácil para o tradutor ver quantas strings foram traduzidas para tornar a compilação do documento final utilizável.

9.7. Submetendo a Nova Tradução

Prepare os novos arquivos de tradução para envio. Isso inclui adicionar os arquivos ao sistema de controle de versão, definir propriedades adicionais e criar um diff para a submissão.

Os arquivos diff criados por esses exemplos podem ser anexados a um relatório de bug de documentação ou revisão de código.

Exemplo 4. Tradução Espanhola do Artigo NanoBSD
  1. Crie um diff dos novos arquivos a partir do diretório base ~/doc/ para que o caminho completo seja mostrado com os nomes dos arquivos. Isso ajuda os committers a identificar o diretório do idioma de destino.

    % cd ~/doc
    % git diff documentation/content/es/articles/nanobsd/ > /tmp/es_nanobsd.diff

Última alteração em: 6 de fevereiro de 2022 por Danilo G. Baio