O preocupante estado da documentação pt_BR do PHP

TL;DR;

A documentação em português brasileiro está abandonada e precisando de sua ajuda! Para mais informações de como ajudar, a lista abaixo lhe fornece tudo o que você precisa para começar!


 

Há algum tempo como membro do PHP Team, tenho dados suficientes para informar que a documentação pt_BR do PHP está sofrendo e precisa de sua ajuda, mais do que se imagina.

O estado atual

Pt_BR possui 10% de arquivos atualizados
Pt_BR possui 10% de arquivos atualizados

Como pode ser observado no gráfico acima, apenas 10% (na verdade são 11%), de toda a documentação está atualizada para a versão pt_BR. E esse é somente um dos nossos problemas.

Há quatro estados a serem levados em consideração da documentação. São eles: Up to date files, Outdated files, Files without revision number, Files available for translation. Cada um contemplando uma gama incrível de arquivos que merecem sua atenção.

O processo de acompanhamento das traduções é orientado ao número de revisão na árvore en da documentação, e existem ferramentas do próprio “the PHP Group” para acompanhar os problemas relacionados acima.

Subdivisão do estado atual da documentação pt_BR
Subdivisão do estado atual da documentação pt_BR

Na publicação deste artigo, haviam 11602, arquivos disponíveis para tradução na versão en da documentação, abaixo subdivido esse número e levanto o que eles realmente significam.

Up to date files (1021 arquivos — 11.39%)

Como dá pra se inferir pelo nome, são os arquivos atualizados com a árvore en. Os arquivos que entram para esse grupo são aqueles que possuam na tag de acompanhamento, a mesma revisão que a versão en. Abaixo ilustramos a situação:

Seleção_003
En-Revision idêntica a Revisão da versão em inglês

Arquivos atualizados são nossa pior situação. Pode parecer absurdo, mas nestes que encontramos os problemas mais gritantes. Diversos arquivos, marcados como atualizados apresentam problemas de grafia em português, falta de concordância, e completa falta de sentido em algumas frases. Minha missão principal nos últimos três meses foi atacar estes problemas. Coisas como “essessão”, “extende”, “zona de tempo e tempo de zona” (a pessoa procurava a tradução de timezone, que é fuso horário), não existem mais nas páginas principais da documentação.

Outro problema não tão sério, mas que deve ser levado em consideração é a pessoalidade empregada na documentação. No manual oficial, diz-se que deve-se empregar a impessoalidade, transformando frases como:

You can use the optional second parameter to specify tags that should not be stripped.

em

The optional second parameter may be used to specify tags that should not be stripped.

Outdated Files (465 arquivos — 4.31%)

Os arquivos marcados como desatualizados são aqueles que possui o número de revisão, na tag de acompanhamento inferior à língua inglesa. Esses arquivos representam apenas uma pequena parcela do problema, mas ele pode ser um dos mais complexos.

Essa complexidade está associada ao fato de que, diversas pessoas iniciam seus estudos pela linguagem PHP, e esta, muitas vezes não possui conhecimentos suficientes para usar a versão em inglês, e pra ser sincero, ela não deveria, se tivéssemos uma documentação atualizada e com qualidade. O problema é que estes novos usuários estão se atualizando com material desatualizado, o que pode trazê-los infortúnios, se a situação atual não mudar.

Um exemplo deste problema era a página sobre o tipo array, que por anos não recebia uma atualização, sendo que diversos recursos foram adicionados ao tipo, e aqueles que primavam por ler a versão em nosso idioma, viam somente uma versão truncada da página.

Files without revision number (841 arquivos — 10.43%)

Pela quantidade de arquivos nessa situação, coloco este problema em segundo lugar na lista de prioridades, já que aqueles nesta categoria não possuem tag de revisão para fazer o acompanhamento, sendo assim, não existe a possibilidade de acompanhar se os arquivos estão, ou não, atualizados.
Este problema foi introduzido na migração, em 2009, do CSV para SVN.

Files available for translation (9273 arquivos — 73,88%)

Esta categoria, representa o estado atual de nossa documentação: Completo abandono. São muitos arquivos esperando tradução, e levando em consideração não só o volume de arquivos, mas também a quantidade de strings a serem traduzidas não existe um cenário onde um dia alcançaremos ao menos 90% da documentação, se observado o cenário atual.

O que é feito atualmente para mudar isso?

Além do trabalho diário feito pelos tradutores ativos (eu e outro), anualmente, em escala mundial, acontecem as “Translation Fests”, eventos que, por um dia inteiro, reune pessoas do mundo inteiro para traduzir nosso manual. A versão tupiniquim do evento, sempre possui pouquíssimos participantes não suplantando a necessidade.

O problema é que estes eventos não resolvem o problema. Não na situação que temos hoje. O problema é grande para ser resolvido em apenas um dia.

Como resolver o problema?

Não existe resolução para esse problema senão o envolvimento de toda a comunidade. A conscientização que a documentação é a porta de entrada de grande maioria dos usuários deve estar em mente ao se pensar se começarão ou não a traduzi-la!

A documentação atualizada pode garantir  profissionais de qualidade, solução a problemas conhecidos que não estão disponíveis na versão pt_br(em caso dos arquivos desatualizados), e o mais óbvio, o engajamento da comunidade!

Sendo assim, convoco os grupos de usuários a conscientização de seus membros sobre a importância da tradução.

Aqueles que tiverem interesse em começar a traduzir e quiseram maiores informações sobre o processo, podem entrar em contato comigo, no e-mail fabioluciano@php.net ou fabio@naoimporta.com, ou na lista de emails oficial da tradução em português brasileiro.