Ajuda:Extensão:Translate/Guia do programador

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

A extensão 'Translate' é uma extensão grande com centenas de classes. Esta página fornece orientação para os programadores que pretendem trabalhar no código. Depois de ler esta página e os documentos vinculados, você entenderá melhor como o código no Translate é organizado e quais convenções especiais são usadas. Políticas gerais de desenvolvimento do MediaWiki, convenções de codificação e como usar ferramentas como Gerrit e Phabricator estão fora do escopo. Presume-se que você já esteja familiarizado com esses tópicos e, quando eles se aplicam ao Translate, não serão repetidos aqui.

A extensão Translate está passando por muitas migrações grandes simultaneamente. Aqui listamos as principais migrações que estão em andamento e detalhamos qual estilo é preferido para o novo código. Em geral, ao modificar o código existente, é melhor manter o estilo atual e fazer as migrações separadamente. Não há problema em fazer algumas limpezas menores ao mexer no código.

Migração de espaços de nome

Estamos em processo de migração de todo o código do Translate para o namespace \MediaWiki\Extension\Translate. Todo o código namespaced é colocado no diretório src/. Todos os novos arquivos PHP devem ser colocados em um namespace apropriado. Consulte Extension:Translate/Namespaces para obter orientação sobre quais namespaces estarão disponíveis. Os namespaces são organizados por domínio, e não por função. As abreviações devem ser evitadas em namespaces e nomes de classes. O código legado está na raiz do repositório e em vários subdiretórios.

No Gerrit, o SonarCube calcula a cobertura da revisão de código somente para o código em um diretório de src/.

Dividir testes em integração e testes unitários

Anteriormente, não havia distinção entre testes de integração e de unidade. Para novos códigos, os testes de unidade devem ser o principal tipo de teste. Os testes de unidade são colocados em um diretório de tests/phpunit/unit que corresponde ao layout do namespace. Há um Makefile nesse diretório para executar facilmente todos ou partes dos testes de unidade durante o desenvolvimento.

Declarações de tipo e comentários

Todo código novo deve declarar os tipos de parâmetro e de retorno. Além disso, os tipos estritos devem ser ativados usando declare( strict_types = 1 );.

Graças às declarações de tipo, a maioria dos comentários de funções e métodos agora é redundante, pois eles apenas repetiriam os nomes e os tipos dos parâmetros. Não adicione documentação redundante, a menos que ela ofereça valor adicional. Um exemplo disso é fornecer dicas de tipo mais precisas para tipos de matriz, por exemplo:

class UserManager {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

Conforme ilustrado acima, para comentários com apenas uma tag ou descrição de uma linha, use também a sintaxe de comentário de uma linha.

Não há nenhuma restrição quanto ao espaçamento em torno de : nas declarações de tipo de retorno. Até que esse padrão seja adotado, use o estilo ilustrado: sem espaço antes, um espaço depois.

Injeção de dependência do construtor

O novo código deve ter todas as suas dependências injetadas por meio do construtor. Em alguns casos, isso ainda não é possível devido à falta de suporte do ObjectFactory para alguns tipos de classes, como trabalhos e scripts de manutenção. Para esse novo código, coloque todas as dependências no construtor da classe (ou no ponto de entrada principal da classe) para facilitar a migração para a injeção de dependência do construtor no futuro.

Os scripts de manutenção não podem usar nenhum código que exija o carregador automático do PHP, portanto, todas as dependências só podem ser declaradas no método execute, não no construtor.

Cabeçalhos do ficheiro

Para o novo código, escolhemos o seguinte cabeçalho minimalista:

<?php
declare( strict_types = 1 );

namespace Example;

use OtherStuff;

/**
 * Class description.
 * @author Your name
 * @license GPL-2.0-or-later
 * @since 2020.06
 */
class ExampleClass {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

Se desejar afirmar seus direitos autorais de forma mais explícita, você também pode adicionar opcionalmente a tag @copyright.

Números de descontinuação e versão

Ao alterar o código do Translate de forma incompatível com as versões anteriores, verifique o https://codesearch.wmcloud.org/search/ para todos os usuários do código. Os usuários conhecidos são TwnMainPage, TranslateSVG, CentralNotice, MassMessage e um monte de coisas no repositório translatewiki.

Você pode usar os recursos de depreciação fornecidos pelo núcleo do MediaWiki, incluindo a tag @deprecated e a depreciação rígida wfDeprecated(). Se não houver usuários conhecidos do código, não há problema em alterá-lo de forma incompatível com as versões anteriores sem depreciação, a menos que ele seja explicitamente marcado como estável (consulte Política de interface estável). O código marcado como estável deve ser descontinuado pelo menos para uma versão de Pacote da Extensão de Línguas da MediaWiki (MLEB).

Os números de versão do núcleo do MediaWiki não fazem sentido no contexto do Translate, pois o Translate sempre oferece suporte a várias versões do MediaWiki. O próprio Translate usa o estilo de versão AAAA.MM (como parte do MLEB). Novas classes e métodos devem ser anotados com tags @since AAAA.MM.