Ajuda:Extensão:Traduzir/Suporte a formato de arquivo

Documentação para a extensão Extensão:Translate

Tradutores (página de ajuda principal )

• Como traduzir
• Melhores práticas
• Estatísticas e relatórios
• Garantia de qualidade
• Estados de grupo de mensagens
• Tradução off-line
• Glossário

Administradores de tradução

• Como preparar uma página para tradução
• Administração da tradução de páginas
• Tradução de elementos não estruturados
• Gerenciamento de grupo
• Mover página traduzível
• Importar traduções via CSV
• Trabalhando com pacotes de mensagens

Administradores e desenvolvedores

• Instalação
• Configuração
• Introdução ao desenvolvimento
• Guia do desenvolvedor
• Ampliação da extensão
• Validadores
• Inseríveis
• Configuração do grupo
• Exemplo de configuração de grupo
• Memórias de tradução
• Auxílios à tradução
• Ativação de pacotes de mensagens
• Ganchos PHP

Traduzir esta predefinição

FFS significa suporte a formato de arquivo. Esse é o nome geral de um grupo de classes para leitura e gravação de mensagens traduzidas em diferentes formatos de arquivo na extensão Translate.

Os desenvolvedores de software reinventaram a roda com tecnologias de localização muitas vezes, portanto, há muitos formatos diferentes para armazenar mensagens de software traduzíveis. Há dois grupos principais desses formatos.

• Formatos baseados em chaves: cada mensagem tem uma chave, geralmente uma cadeia de caracteres mais ou menos significativa. A tradução para cada idioma é um mapa de chaves que apontam para valores. A maioria dos formatos se enquadra nesse grupo, incluindo DTD, JSON e o antigo formato do MediaWiki até 2014 (essencialmente uma matriz PHP).
• Do tipo gettext: A mensagem no idioma original do programa, geralmente o inglês, é usada como uma chave que aponta para traduções em outros idiomas. Isso requer a geração de pseudochaves inerentemente não estáveis para armazenar as mensagens em um formato diferente.

Introdução às classes FFS

Com algumas exceções, a maioria das classes FFS deriva da interface FFS, que define os métodos básicos que cada classe deve implementar:

setWritePath( $target )

Setter para o nome do arquivo.

getWritePath()

Getter para o nome do arquivo.

read( $code )

Leia as mensagens do arquivo e analise-as.

readFromVariable( $data )

Leia as mensagens de uma variável de cadeia de caracteres que tenha o mesmo formato do arquivo e retorne-as como uma matriz de AUTORES e MENSAGENS. É aqui que a análise real do texto do arquivo deve ocorrer.

write( MessageCollection $collection )

Gravar as mensagens no arquivo.

writeIntoVariable( MessageCollection $collection )

Grave as mensagens em uma variável de cadeia de caracteres que tenha o mesmo formato do arquivo. É aqui que deve ocorrer a construção cuidadosa do arquivo de mensagens resultante.

Traduções do MediaWiki

As classes para armazenar as traduções do MediaWiki não são atualmente tratadas por derivados da interface FFS, mas por classes autônomas: há instruções de configuração. Novas classes do tipo FFS estão sendo desenvolvidas.

classe SimpleFFS

A classe SimpleFFS é o ancestral de todas as outras classes FFS e também é um exemplo simples de como uma classe FFS deve ser escrita. Ela implementa um formato simplista baseado em chave:

• cada arquivo tem duas seções, separadas por "\0\0\0\0";
• uma seção tem os nomes dos tradutores separados por "\0";
• o outro tem as traduções no formato "key=value", também separadas por "\0".

Como o SimpleFFS é intencionalmente simplista, ele demonstra possíveis erros e complicações. Por exemplo, o caractere "=" não é escapado e, portanto, a chave e o valor podem não conter esse caractere. Obviamente, isso não é adequado para programas do mundo real. O SimpleFFS também implementa métodos utilitários úteis:

exists( $code )

Testa se o arquivo existe.

writeReal( $collection )

Implementa os aspectos internos da gravação de formato de arquivo, além do writeIntoVariable mais genérico.

filterAuthors

Filtre alguns autores definidos do arquivo de acordo com uma lista negra personalizada. Isso é útil para filtrar nomes de usuário de bots, desenvolvedores e administradores de tradução, por exemplo.

fixNewLines( $data )

Corrigir todos os finais de linha para o estilo Unix.

Escrevendo novas classes FFS

Todos os métodos SimpleFFS acima podem ser substituídos. A maioria das implementações, no entanto, só precisa implementar writeIntoVariable e readFromVariable.

Dicas gerais ao escrever novas classes:

• Evite executar formatos de arquivo executáveis. Analise-os.
• Lembre-se de mangle e unmangle message keys.
• Não presuma que as chaves de mensagem não incluam caracteres problemáticos. Eles incluirão.
• Em geral, espera-se que o resultado seja bonito e legível. Algumas pessoas gostam de mexer neles manualmente.
• A maioria dos formatos não suporta marcadores difusos, alguns os adicionam como comentários somente na exportação e os ignoram na importação.

Formatos de arquivo suportados

As classes FFS existentes são:

• AndroidXml - para uso em aplicativos Android
• AppleFFS - para iOS/Mac OS X Localizable.strings
• Dtd - para projetos baseados em DTD, como o Okawix e o Mozilla.
• FlatPhpFFS - para uso futuro no MediaWiki
• Gettext - para projetos baseados em Gettext
• Ini - para projetos baseados em INI
• JavaScript - para todos os arquivos formatados em JavaScript
• Propriedades Java - para arquivos de *.properties, usadas em alguns projetos Java e JavaScript, geralmente junto com Dtd
• Json - usado em projetos baseados em jquery.i18n, como a biblioteca portátil Universal Language Selector
• Yaml - usado em trilhas marcadas
• Ruby (Yaml) - usado no OpenStreetMap e no Shapado
• AMD i18n bundle

Exemplos de exportações da Translate nesses formatos estão disponíveis por translatewiki.net.

Hierarquia de classes FFS

Manipulação das chaves de mensagem para garantir o tratamento correto do título

A extensão Translate é baseada no MediaWiki e cada mensagem é armazenada como uma página do MediaWiki, portanto, a chave deve ser um título de página válido do MediaWiki. O Mangling cuida disso escapando dos nomes das chaves de maneira semelhante à codificação quoted-printable, mas com algumas modificações antes de armazenar a mensagem como uma página wiki. Antes de a mensagem ser gravada de volta no arquivo, ela é desembaraçada.

Quando uma classe FFS substitui as funções que chamam as rotinas de manipulação, ela deve se certificar de que a viagem de ida e volta seja feita corretamente, ou seja, que a chave seja manipulada antes de ser gravada no MediaWiki e não seja manipulada antes de gravar a tradução de volta no arquivo.

A manipulação é feita na classe StringMatcher.

Teste de classes FFS

Se você criar uma nova classe FFS, crie um arquivo de teste correspondente no diretório de testes. Os itens importantes a serem testados são:

• Análise do formato: Essencialmente, testar se a função readFromVariable retorna as chaves e os valores corretos para AUTHORS e MESSAGES.
• Ida e volta: Teste se as chaves e as mensagens estão escritas e lidas corretamente.

Você pode usar rotinas de teste existentes, como o JavaFFSTest, como exemplos.