-
Notifications
You must be signed in to change notification settings - Fork 104
Guia de edição do manual
Esse guia é um resumo do guia original em inglês, PHP Manual Contribution Guide. A leitura do guia original é importante para todos aqueles que desejem se tornar tradutores oficiais do manual, e para além disso, de se tornarem autores ou editores do manual.
Porém o guia original é longo e extenso, e aqui resumimos ao máximo as informações, em português, para permitir um começo bem mais suave aos novos participantes. Esse guia resumido facilita também a vida dos tradutores atuais, ao concentrar comandos de ferramentas e convenções utilizadas na tradução brasileira, onde elas diferem das convenções oficiais, em um único documento.
O Manual do PHP é escrito em arquivos XML seguindo o padrão DocBook. Cada língua do manual é hospedada em repositórios GitHub separados. O manual em inglês fornece a estrutura básica, e as traduções vão lentamente replicando os arquivos em seus próprios repositórios.
Um processo de compilação especial mescla os arquivos traduzidos, complementando os arquivos faltantes com a versão do manual em inglês.
Os fontes do manual em inglês estão hospedados no repositório php/doc-en do GitHub, e a coordenação desse manual ocorre através da maillist [email protected], e também através de issues e pull requests no repositório GitHub.
Os fontes do manual em inglês estão hospedados no no reposiório php/doc-pt_br do GitHub, e a coordenação deste manual ocorre através da maillist [email protected] e também através de issues e pull requests no repositório GitHub da tradução.
Para se inscrever na listas dos originais e da tradução, envie um email para [email protected] e [email protected], respectivamente. E para acompanhar os repositórios, inscreva-se através da funcionalidade de Watch dos repositórios.
Para além dos repositórios de fontes XML, há também o repositório php/doc-base, que contém o ferramental de validação e compilação do manual. Apesar dele ser uma parte importante do Manual do PHP em todas as linguagens, provavelmente somente os coordenadores das traduções acompanham esse repositório, não sendo parte do dia a dia de autores, editores e tradutores GitHub.
O processo de tradução ocorre através da replicação de cada arquivo dos originais em inglẽs, em um arquivo já traduzido no repositório da tradução. Há também um grande trabalho contínuo de atualizações, recriando as alterações realizadas nos originais em inglês nas traduções.
É possível fazer as traduções e atualizações utilizando apenas a interface web do GitHub, mas isso provavelmente só vai funcionar para alterações pontuais. Para fazer traduções de arquivos inteiros, é mais viável clonar os repositórios oficinais e trabalhar com arquivos locais.
O passo a passo de usar a interface web é explicado em um roteiro simplificado. Mas nesse guia estamos focados em traduções completas, e daí vamos utilizar como base o roteiro git em linha de comando, mais completo.
Os arquivos fontes do manual e ferramentas associadas estão publicados em repositórios GitHub, de forma que você não precisa de um acesso especial para realizar uma cópia dos dados. Esse tutorial assume que você tem um conhecimento básico do git. Caso contrário você pode aprender a respeito dessa ferramenta com no livro Pro Git. Há também um guia prático e extremamente resumido disponível em rogerdudler.github.io.
Para baixar os arquivos do manual, utilize os seguintes comandos:
mkdir phpdoc
cd phpdoc
git clone [email protected]:php/doc-base.git doc-base
git clone [email protected]:php/doc-en.git en
git clone [email protected]:php/doc-pt_br pt_BR
git -c pt_BR remote add upstream https://github.com/php/doc-pt_br
git -c pt_BR remote set-url --push upstream /dev/null
git -c pt_BR config pull.rebase true
git -c pt_BR config user.email "[email protected]"
git -c pt_BR config user.name "Nome Completo"
Estes comandos criarão um diretório chamado phpdoc. que irá conter subdiretórios com os fontes em inglês em en, os fontes em português em pt_BR, e as ferramentas de tradução no diretório doc-base.
A sequência de comandos completa para quem for trabalhar no manual em Português do Brasil é explicada no roteiro git. Nesse roteiro consta a versão dos comandos apropriados para utilização de forks, que é o caso para quem está começando na tradução.
A imensa maioria dos arquivos dentro dos diretórios de fontes do manual são arquivos XML simples. Devem ser traduzidos os textos, mas não as tags e atributos XML.
Há alguns arquivos mais importantes ou com funções especiais:
-
translation.xml- Esse arquivo é utilizado como um controle central de informações dos tradutores, podendo ser utilizado também para coordenação. Contém um texto introdutório e uma lista dos tradutores. Esse arquivo não existe na árvore em Inglês; -
language-defs.ent- Contém traduções de entities utilizados pela linguagem, que aparecem copiados em várias partes do manual; -
language-snippets.ent- Entities XML mais longos, traduzidos para a linguagem. Coisas repetitivas como alertas, notas, etc.
Se algum arquivo não existir em uma tradução, o equivalente em inglês será utilizado na compilação do manual. Isso significa que você não deve colocar arquivos sem tradução nos diretórios da tradução. Isso causará confusão na compilação, e poderá fazer com que a compilação do manual pare de funcionar.
Alguns arquivos que existem nos fontes originais não devem ser replicados na tradução se não tiverem texto nenhum. São arquivos que só contém dados estruturais, sem texto traduzível, ou ainda por serem arquivos gerados automaticamente. Em resumo, só copie arquivos em que alguma tradução seja feita, e não replique arquivos sem tradução alguma.
Para ver exemplos desses arquivos "não traduzir e não copiar", veja o conteúdo de arquivos com nomes reference/*/entities.*.xml ou reference/*/versions.xml no repositório de fontes em inglês.
Os fontes do manual seguem uma padronização específica para arquivos texto, a saber:
- Codificação UTF-8, sem BOM;
- Somente fim de linhas
\n; - Indentação somente espaços;
- Espaços a direita removidos.
O texto em si segue um guia de estilo, descrito mais abaixo.
Arquivos em inglês podem conter uma tag de revisão fixa, na forma de um comentário XML <!-- $Revision$ -->. Já os arquivos traduzidos devem conter tag de revisão e créditos, que precisam ser alterados toda vez que um arquivo é atualizado.
Cada vez que fizer alterações nos fontes da documentação, seja no Inglês ou numa tradução, você deve validar essas alterações para garantir que o manual esteja compilado sem erros. O script configure.php realiza essa validação. O que você deve fazer é:
- Para validar o manual em inglês:
php doc-base/configure.php
- Para validar o manual em português brasileiro:
php doc-base/configure.php --with-lang=pt_BR
Quando o processamento acima termina com a mensagem All good. Saving .manual.xml isso significa que a validação passou, e você pode então submeter as alterações.
O envio de alterações segue o fluxo normal do controle de versão git. Primeiro você executa os comandos git add e git commit no seu repositório local, e depois executa um git push contra um repositório público.
Atenção na hora de formular a mensagem que acompanha os commits. É utilizado o seguinte padrão:
Um breve resumo de uma linha, na primeira linha
Um bloco de texto, opcional, contendo a descrição detalhada
das alterações realizadas, separado do resumo com uma linha
em branco, e podendo utilizar formatação Markdown simples,
com linhas limitadas a 70 caracteres ou menos.
Linha final de comandos automáticos.
A linha final reconhece comandos automatizados no formato:
-
Closes GH-nnn-- Automaticamente fecha um issue no GitHub associado; -
Fix #nnnnn: Bug title-- Automaticamente fecha o respectivo bug no bugtracker.
Os tradutores têm acesso para fazer pulls diretamente contra os repositórios oficiais. Para contribuições de pessoas sem acesso direto, após o git pull acima, é necessário iniciar um pull request na interface do GitHub, a partir do seu repositório fork.
O Contribution Guide tem uma página dedicada a explicar como visualizar as alterações localmente, sem ter de esperar o processo de compilação oficial.
A documentação é compilada diariamente às 23:00 CST, e então sincronizada em vários sites espelho. Um site espelho especial está disponível no link docs.php.net, onde a compilação do manual é atualizada a cada seis horas. Se algum erro ocorrer, a mensagem é encaminhada para a lista apropriada ([email protected]). Os logs das compilações estão disponíveis no endereço http://doc.php.net/logs/.
- Arquivos codificados em UTF-8 sem BOM;
- Utilizar somente fins de linha estilo Unix (
\n); - Indentação com espaços;
- Espaços à direita removidos.
Mantenha as linhas dos arquivos XML em comprimentos em até 80 caracteres, mais ou menos. Também é recomendado começar novas sentenças em novas linhas, mesmo que dentro de um parágrafo.
Na tradução brasileira é seguido um outro estilo. Tente fazer com que o arquivo traduzido tenha o mesmo número de linhas que o arquivo original. Em particular, que as linhas contenham quase as mesmas tags, quase nas mesmas linhas, e com a mesma indentação, nem que para isso as linhas traduzidas fiquem bem mais compridas que as linhas do texto original.
Isso porque o Inglês é uma língua bem sucinta, de forma que as linhas traduzidas tendem a serem bem maiores. Manter o mesmo número de linhas, e as tags quase nas mesmas linhas entre original e tradução ajudam enormemente no processo de atualização das traduções, que é a maior parte do esforço.
O XML é indentado com um espaço. Não use tabulações. Para exemplos em código PHP, utilize os padrões específicos para exemplos no manual.
Fontes em Inglês: Pontuação no Manual do PHP segue as regras gramaticais anglófonas. Quando escrevendo sentenças sequenciais, como descrições de funções, pontuação normal deve ser utilizada. Listas, títulos, e fragmentos de sentenças não devem ser pontuadas com ponto final. Sentenças não devem ter dois espaços entre si. Vírgulas e apóstrofos devem ser utilizados apropriadamente.
Fontes em Português: O mesmo se aplica, porém utilizando as regras do último Acordo Gramatical. Em específico, não é comum em Português que o conectivo e seja precedido de vírgula (ao contrário do parágrafo acima, onde foi copiado o estilo em Inglês) e adjetivos e outros qualificativos precedem o substantivo (sendo que o Inglês adota o inverso).
O Manual do PHP é um documento técnico, e assim deve estar escrito. O uso de "você" é comum no manual, o que o deixa com uma aparência pouco profissional. Somente é permitido a personificação em duas seções: o Tutorial e nas FAQs.
Exemplo incorreto: Você pode utilizar o segundo parâmetro opcional para indicar tags que não devem ser eliminadas.
Exemplo correto: O segundo parâmetro opcional pode ser utilizado para indicar tags que não devem ser eliminadas.
Vários termos técnicos em línguas estrangeiras são utilizados no corpo do manual, sem uma indicação do estilo apropriado a ser utilizado.
Em Português, alguns termos são traduzidos, alguns não. Termos antigos normalmente utilizados na área não são traduzidos (por exemplo: string), enquanto que termos com equivalentes comuns são traduzidos (por exemplo: função, exceção), e termos pouco comuns são mantidos no original mesmo que sejam recentes (thread, prefork).
Infelizmente não existe uma distinção clara ou vocabulário padronizado do que traduzir ou não, então isso fica por conta da sensibilidade do tradutor. Em último caso, evita-se traduzir os termos quais se espera encontrar numa conversa entre profissionais de informática, em vez da tradução visando um completo iniciante. Por exemplo: thread em vez de encadeamento, trait em vez de caraterística, e assim por diante.
O PHP Manual Contribution Guide contém uma série de apêndices, com informações pontuais. Replicar aqui os apêndices seria contraproducente. A seguir é dado um resumo dessas informações, mas fica a sugestão de ler o texto original.
O primeiro apêndice é uma FAQ, com informações pertinentes sobre como documentar uma nova extensão, como fazer links para métodos de classe, como documentar informações de versionamento, links externos, formatação de notas, documentação de parâmetros opcionais e como lidar com texto repetitivo.
O segundo apêndice contém detalhes ferramentas de qualidade auxiliares, tanto para o manual em inglês, como para traduções.
Os demais apêndices tratam de tags e entidades mais usadas no manual, como editar as notas de usuários, como visualizar o manual no computador local, e detalhes finais sobre como o manual é compilado e disponibilizado no site oficial.
Se você sentir que gosta desse tipo de trabalho, e o está realizando regularmente, existe uma forma mais eficiente de utilizar pull requests, que é modificar os repositórios GitHub diretamente. Isso requer uma conta no GitHub e permissões nos repositórios oficiais do PHP. Depois de realizar traduções por alguns meses, converse com os tradutores/autores, e pergunte como solicitar o acesso direto.