current
Line 1:
Line 1:
+
===== Brazilian Portuguese PHP Manual: A crash course =====
+
In this page we provide a crash course to new translators and other contribuitors for the pt_BR manual. This page will be written in Brazilian Portuguese.
+
+
==== Onde e oque ====
+
+
A tradução do manual do PHP é coordenada através de uma //maillist//. Se inscreva mandando um e-mail para [[doc-pt-br-subscribe@lists.php.net|doc-pt-br-subscribe@lists.php.net]]. Para conversar o endereço é [[doc-pt-br@lists.php.net]]. O histórico pode ser visualizado em [[http://news.php.net/php.doc.pt-br]] ou acompanhado por um cliente de NEWS em [[news://news.php.net/]].
+
+
A documentação é mantida em um repositório SVN que possui acesso de leitura liberado mas acesso de escrita restrito a pessoal com credencial e autorizações específicas. É preciso primeiro contribuir sem ter credencial (enviando //patchs//) antes de pedir uma conta php.net e acesso de escrita ao manual.
+
+
O manual é compilado a partir dos fontes a cada 4 horas. Não raro o resultado da compilação oficial é diferente da validação local, razão pela qual as vezes é preciso verificar o último resultado da compilação oficial, principalmente quando uma tradução/atualização não aparecer no site oficial depois de 8 horas. Logs disponíveis em [[http://doc.php.net/logs/]].
+
+
Para contribuir com o manual são quatro passos, assim resumidos:
+
+
- Baixar ou atualizar os arquivos fontes.
+
- Traduzir ou sincronizar uma tradução.
+
- Validar a consistência do manual.
+
- Gerar um patch e o submeter.
+
+
Embora seja possível utilizar ambientes Windows (e outros) para traduzir o manual, o ambiente explicado aqui é um Linux (especificamente Ubuntu) dada a facilidade de instalação (ou virtualização) dessa distribuição em particular.
+
+
==== Passo 0: Obtendo os fontes ====
+
+
Os fontes são gerenciados num repositório SVN. Então para trabalhar na tradução é necessário instalar um cliente SVN para o seu sistema operacional ou utilizar um [[https://wiki.php.net/doc/translations/pt_br#prepare_o_ambiente_e_ajude_a_contribuir_com_a_traducao|ambiente virtualizado com o ferramental já instalado]].
+
+
Num terminal, verifique se possui o cliente SVN instalado:
+
svn --version | head -n 1
+
+
Caso não possua instalado, execute:
+
sudo apt-get install subversion
+
+
É preciso baixar os fontes uma única vez. Para tanto, execute:
+
svn co https://svn.php.net/repository/phpdoc/modules/doc-pt_BR phpdoc
+
+
Isso irá criar uma pasta ''phpdoc'' no mesmo diretório que o comando for executado. Toda a tradução acontecerá aqui. Para entrar na pasta e ver o seu conteúdo:
+
cd phpdoc
+
ls
+
+
Haverão três diretórios aqui:
+
+
* **doc-base**: Contém scritps e outros arquivos necessários a compilação do manual.
+
* **en**: Contém os originais do manual, em inglês.
+
* **pt_BR**: Contém as traduções do manual, especificamente a tradução para português do Brasil.
+
+
Você somente vai mexer com arquivos dentro de ''pt_BR''. As demais pastas nunca serão parte da geração de patchs, justamente para evitar subir qualquer coisa que tenha mexido nelas.
+
+
==== Passo 1: Atualizando os fontes ====
+
+
Para trabalhar a partir dos fontes mais atuais possíveis, sempre comece com um:
+
svn update
+
+
Isso vai atualizar os três diretórios. Além disso é interessante antes de começar a trabalhar numa tradução de também executar:
+
php doc-base/configure.php --enable-xml-details --with-lang=pt_BR
+
+
Esse script verifica a integridade do XML. Está tudo bem se no final aparecer um gatinho em ASCII art. Se acabar em erro o jeito é trabalhar no erro primeiro, já que começar com o manual inconsistente impede de realizar o passo 3.
+
+
Para facilitar, você pode criar um script bash que realize esses passos numa tacada só.
+
echo svn update >> sync.sh
+
echo php doc-base/configure.php --enable-xml-details --with-lang=pt_BR >> sync.sh
+
chmod +x sync.sh
+
ls
+
+
Para executar, basta chamar um ''./sync.sh'' ou ''source sync.sh''.
+
+
E aqui surge a primeira regra geral: **Antes de começar, atualize e valide.**
+
+
==== Passo 2: Traduzir ou atualizar um arquivo ====
+
+
Atualmente os arquivos a traduzir são listados e coordenados num painel [[https://trello.com/b/j6Nuulpn/lista-de-tarefas-traducao-pt-br|Trello]]. Escolha um arquivo listado em ''Pendente'' e mova o card para ''Em Andamento''. Caso não possua acesso, avise na lista de discussão que vai começar a mexer em tal arquivo, para que alguém com acesso fazer a movimentação de cards, além do e-mail em si ser uma forma de notificação.
+
+
O processo de tradução em si é bem simples. Original e tradução tem sempre os mesmos caminhos relativos, mudando apenas a pasta inicial, ''en'' ou ''pt_BR''. No caso da tradução de arquivo inexistente em ''pt_BR'' crie-o, simplesmente. Depois é abrir ambos os arquivos, original e tradução, e traduzir a parte texto, preservando tags e comentários no final do arquivo.
+
+
**Dica 1:** 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 2:** 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 em [[http://www.youtube.com/watch?v=ytJMMaFG7W0&t=6m19s|video]]. Assista entre 6:19 e 13:15.
+
+
Assim que terminar a tradução, é preciso sincronizar a tag de tradução. Isso está rapidamente explicado no mesmo vídeo, [[http://www.youtube.com/watch?v=ytJMMaFG7W0&t=13m15s|entre 13:15 e 13:56]], mas basicamente as tags de tradução tem o seguinte estrutura:
+
<!-- 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 do original e se insere nos créditos se tiver uma 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.
+
+
==== Passo 3: Validar a consistência do manual ====
+
+
Antes de encaminhar patchs é estritamente necessário validar se a alteração não quebra a compilação do manual. Isso é feito através do comando
+
php doc-base/configure.php --enable-xml-details --with-lang=pt_BR
+
+
Caso tenha definido o ''sync.sh'' acima, basta executá-lo. Porém isso vai atualizar o manual antes de compilar. Isso pode ser bom por um lado (melhora a certeza que o manual compilará //depois// que enviar o patch), mas pode ter o efeito colateral de quebrar a sua compilação //local// por causa de alguma alteração de terceiros, o que dificulta o problema de separar se a quebra é por conta de alguma alteração sua ou de algo trazido na atualização.
+
+
Mas não tem escapatória. Ninguém vai aplicar um patch com o manual quebrado desde antes antes, menos vai aplicar um patch que quebre a compliação do manual, então melhor correr atrás de ter o manual sempre validando. Daí vem a segunda regra geral: **Antes de gerar o patch atualize e valide.**
+
+
Ou o que é mais fácil: **Antes e depois de traduzir, rode um ./sync.sh**
+
+
>>> Observação: Na verdade existe uma maneira de [[https://wiki.php.net/doc/translations/pt_br#compilando_o_manual|visualizar]] suas alterações localmente, sem esperar a publicação no site oficial. Mas isso também exige a instalação de um [[https://wiki.php.net/doc/translations/pt_br#dependencias|toolchain]] bem mais complicado. É bem possível conviver só validando o manual localmente, preocupando-se principalmente com a corretude do texto e nem tanto com o visual final.
+
+
==== Passo 4: Gerar um patch e o submeter ====
+
+
A geração de patchs utiliza do próprio cliente do SVN. Porém como os patchs contém caminhos relativos então alguma uniformização de //onde// os patchs são gerados é necessária para organizar o processo. A padronização também evita que diretórios que //não// devem ser alterados estejam incluídos na geração.
+
+
Para gerar um patch, você deve estar na pasta ''phpdoc/pt_BR''. Você pode confirmar isso rodando o comando:
+
pwd
+
+
Isso vai retornar o caminho atual do seu terminal. Esse caminho tem de terminar exatamente com ''/phpdoc/pt_BR''. Não deve ser um diretório interno de ''pt_BR'' para não dificultar a vida de quem aplica os patchs, e nem pode ser no nível ''phpdoc'' para evitar subir algo nos originais (ou do maquinário) do manual.
+
+
Estando no diretório correto, execute:
+
svn diff > minha_traducao.patch
+
+
Isso criará um arquivo com o nome ''minha_traducao.patch''. Pode ser criativo aqui, mas evite espaços. Encaminhe esse arquivo para a [[doc-pt-br@lists.php.net|lista de email]]. Depois acompanhe pela própria lista a aplicação do patch, e posteriormente a publicação de sua contribuição no site oficial.
+
+
Esse é o último passo para quem não tem credencial no php.net. Quanto mais patchs aprovados tiver mais fácil será de obter, depois, uma credencial php.net de forma que você mesmo possa enviar as alterações diretamente.
+
+
E é isso. GOTO STEP 1.
+
+
==== Questões avançadas ====
+
+
=== A versão completa ====
+
+
Existe a versão completa desse roteiro, com muitos mais detalhes, disponível em [[https://wiki.php.net/doc/translations/pt_br]]. Esse crash course, bem resumido, é mais para tirar o pessoal do zero. Aparentemente a versão grande muito assusta. Essa versão "faz enquanto aprende" é uma tentativa de diminuir a barreira inicial. Mas depois que tiver feito todo o processo, dê uma lida lá.
+
+
+
=== E o editor online? ===
+
+
Existe disponível para edição do manual, original em inglês e traduções, uma ferramenta web chamada [[https://wiki.php.net/doc/editor|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, ainda que menos amigável, é o procedimento que efetivamente faz as contribuições chegarem no manual traduzido.