In this page we provide a crash course to new translators and other contribuitors for the pt_BR manual using GitHub interface. This page will be written in Brazilian Portuguese.

Este roteiro é destinado àqueles que querem contribuir com o manual do PHP utilizando as interfaces web do GitHub. É especificamente destinado àqueles que desejem fazer uma contribuição ao manual sem instalar programas ou lidar com a linha de comando.

Esse mesmo roteiro existe para quem prefere usar o SVN em linha de comando ou o Git em linha de comando. Respectivamente o processo oficial e indireto, mas altamente produtivos, para quem já conhece esses sistemas de controle de versão.

Para contribuir com o manual utilizando o GitHub são dois passos, assim resumidos:

1. Atualizar o seu fork
2. Traduzir ou sincronizar um arquivo.
3. Enviar um pull request.

Para usar o GitHub é preciso criar uma conta em https://github.com/join. O processo é bem rápido, e a conta é ativada instantaneamente.

Depois de logar, acesse https://github.com/alfsb/phpdoc-pt_BR e acima e a direita clique em Fork. Um fork é uma cópia do repositório na sua conta, de forma que isso lhe dá acesso total a essa cópia, permitindo a você livremente criar, editar e apagar arquivos.

Isso só é necessário uma única e primeira vez. Depois do fork criado, vem os passos normais de tradução.

O seu fork vai se diferenciando do repositório ponte com o tempo. Antes de traduzir é preciso atualizar o seu fork a partir do repositório oficial. Os passos são demonstrados aqui: http://www.hpique.com/2013/09/updating-a-fork-directly-from-github/

Casos extremos, em que esse procedimento não funcione ou os pull requests gerados estejam causando conflitos no repositório ponte, o jeito é destruir o seu fork e começar do passo zero, acima.

O manual do PHP é um documento enorme, e trabalho não falta. Você pode escolher que tipo de contribuição realizar. Em ordem de prioridade:

1. Arquivos desatualizados: Arquivos anteriormente traduzidos mas que foram posteriormente tiveram os originais atualizados.
2. Arquivos sem tags: Arquivos traduzidos mas que a ausência de tags de tradução (ver abaixo) impedem acompanhar a sincronia.
3. Not in EN tree: Arquivos que existem na tradução mas não original. Provavelmente movidos, ou mesmo a apagar.
4. Arquivos não traduzidos: Aparecem no manual totalmente em inglês.

O processo de tradução em si é bem simples. Para os arquivos desatualizados (caso 1), a listagem contém um link [diff] por arquivo, qual fornece o resumo das alterações necessárias para atualizar a tradução. Basta localizar o mesmo arquivo dentro do seu fork, realizar as alterações destacas no link [diff] já traduzindo os textos, e gravar o arquivo no GitHub.

Os demais casos exigem um trabalho maior, de baixar o arquivo no original e fazer uma bela revisão linha a linha (sem tag de tradução) ou mesmo uma tradução completa. Em ambos os casos é preciso ter a mão os arquivos originais, situação que é explicada abaixo, na seção “Questões Avançadas”.

Assim que terminar a tradução, é preciso sincronizar a tag de tradução. Isso está rapidamente explicado nesse video, entre 13:15 e 13:56, mas em resumo, a segunda linha do arquivo deve estar no formato:

<!-- EN-Revision: nnnnnn Maintainer: xxxx Status: ssss --><!-- CREDITS: yyyy,zzzz -->

Onde:

• nnnnnn: É o número que aparece no original, o arquivo em inglês.
• xxxx: É o login do tradutor do manual, uma credencial php.net. Caso não possua deixar como none.
• ssss: É um código de status, conforme definido abaixo.
• yyyy,zzzz: Uma relação de logins dos tradutores com credencial php.net. Logins separados por vírgula.

Os valores previstos para o Status são:

• ready: Significa que a tradução está pronta.
• revision: Significa que a tradução está pronta, mas que o tradutor solicita que outra pessoa revise.
• wip: Work in progress. Um tradutor reservou esse arquivo para tradução. Entre em contato com ele ou discuta a situação na lista, caso encontre um arquivo ainda WIP depois de muito tempo.

Basicamente sincroniza o número da tradução com o número que aparece no arquivo original e insere seu nome/login na lista CREDITS, se tiver um credencial php.net. Se quiser pegar a manutenção do arquivo para si (e se possuir uma credencial php.net), você pode substituir o xxxx por seu login. Caso não possua uma credencial php.net, os créditos são dados na mensagem de commit.

Para disponibilizar suas alterações é preciso criar um pull request. O procedimento é o mesmo demonstrado no primeiro vídeo acima, com poucas diferenças.

No seu GitHub clica em Pull Requests e depois em New pull request. As diferenças vão aparecer. Revise-as e depois clique na caixa de texto para dar um título ao pull request. Clica por fim em Send pull request. Assim aparecerá no repositório ponte as suas alterações para posterior integração no repositório oficial do PHP.

E é isso. Repetir o processo :)

Existe a versão completa desse roteiro, com muitos mais detalhes, está disponível em https://wiki.php.net/doc/translations/pt_br. Esse crash course, bem resumido, é mais para quem quer fazer contribuições ao manual do PHP sem fazer a instalação de programas.

Muitos outros detalhes, não mencionados aqui, só são possíveis com o ferramental correto instalado. Ao utilizar a rota do GitHub esses procedimentos vão recair ao tradutor que tenha ferramental apropriado.

Existe disponível para edição do manual, original em inglês e traduções, uma ferramenta web chamada editor online. Porém não há tradutores brasileiros cuidando do backlog gerado por essa ferramenta, de forma que as contribuições lá ficam emperradas por meses a fio.

O roteiro acima, até amigável, é um procedimento EXPERIMENTAL que visa substituir essa deficiência.

A melhor maneira é mesmo adotando a linha de comando, seguindo os roteiros específicos do SVN ou Git.

Uma alternativa mais simples é instalar um cliente gráfico do SVN, como o TortoiseSVN e através dele baixar os fontes originais do manual, que estão disponíveis da URL https://svn.php.net/repository/phpdoc/en/trunk.

Isso permitirá abrir os arquivos lado a lado, originais e traduções, e assim revisá-los ou traduzir novos. Terminado a revisão/tradução, daí é colocar o arquivo no GitHub e submeter um pull request normalmente.

Dica: Alguns editores de texto permitem abrir arquivos em abas, e possuem atalhos para rapidamente navegar entre abas. Daí se abrir original e tradução em abas, o rápido alternar entre abas permite facilmente detectar alterações estruturais, que precisem de tradução/sincronização, assim como verificar se a estrutura em si está sendo mantida. Alguns editores permitem abrir dois arquivos lado a lado, o que é mais confortável para traduzir, ainda que dificulte um pouco a comparação estrutural.

Dica: Tente preservar a quantidade igual de linhas entre os arquivos, além de manter as tags estruturais nas mesmas linhas entre original e tradução. Isso fará muita diferença for fazer atualização de traduções. É muito mais fácil detectar o que é preciso atualizar quando essa “compatibilidade estrutural” é preservada. Veja a demonstração disso video. Assista entre 6:19 e 13:15.