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 de tradução de páginas
• Tradução de elementos não estruturados
• Gerenciamento de grupo
• Move translatable page
• Import translations via CSV
• Working with message bundles

Administradores e desenvolvedores

• Instalação
• Configuração
• Getting started with development
• Developer guide
• Ampliação da extensão
• Validators
• Inseríveis
• Group configuration
• Group configuration example
• Translation memories
• Translation aids
• Enabling message bundles
• PHP hooks

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. After reading this page and linked documents you will better understand how code in Translate is organized and what special conventions are used. General MediaWiki development policies, coding conventions and how to use tools like Gerrit and Phabricator are out of scope. You are assumed to be familiar with these topics and when they apply to Translate, it will not be repeated here.

Translate extension is undergoing many large migrations simultaneously. Here we list the major migrations that are on-going, and detail which style is preferred for new code. Generally, when modifying existing code, it is better to keep to current style, and do migrations separately. Some smaller cleanups are okay to do when touching code.

Migração de espaços de nome

We are in process of migrating all Translate code under the namespace \MediaWiki\Extension\Translate. All namespaced code is placed under the src/ directory. All new PHP files should be put in an appropriate namespace. See Extension:Translate/Namespaces for guidance which namespaces are going to be available. Namespaces are organized by domain, rather than function. Abbreviations should be avoided in namespaces and class names. Legacy code is in the repository root and various subdirectories.

In Gerrit, SonarCube calculates code review coverage only for code under src/ directory.

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

Previously there was no distinction of integration and unit tests. For new code, unit tests should be the main type of tests. Unit tests are placed under tests/phpunit/unit directory matching the namespace layout. There is a Makefile in that directory to easily run all or parts of unit tests while developing.

Declarações de tipo e comentários

All new code should declare both parameter and return types. In addition strict types should be enabled using declare( strict_types = 1 );.

Thanks to type declarations, most function and method comments are now redundant, as they would only repeat the parameter names and types. Do not add redundant documentation unless it provides additional value. One such example is to provide more accurate type hints for array types, for example:

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

As illustrated above, for comments having only one tag or one line description, do use the one line comment syntax as well.

There is no linter about spacing around : in return type declarations. Until such standard comes, please use the illustrated style: no space before, one space after.

Injeção de dependência do construtor

New code should have all its dependencies injected via constructor. Em alguns casos ainda não é possível, devido a alguns serviços estarem disponíveis apenas na versão mais recente do MediaWiki, bem como a falta de suporte da ObjectFactory para alguns tipos de classes como trabalhos e comandos de manutenção. For such new code, place all dependencies on the class constructor (or main entry point to the class) to easy migration to constructor dependency injection in the future.

Maintenance scripts cannot use any code that requires PHP autoloader, hence all dependencies can only be declared in the execute method, not in the constructor.

Cabeçalhos do ficheiro

For new code, we have chosen the following minimalistic header:

<?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 { ... }
}

If you wish to assert your copyright more explicitly, you can optionally add @copyright tag as well.

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

When changing Translate code in backwards incompatible ways, do check https://codesearch.wmcloud.org/search/ for any users of the code. Known users are TwnMainPage, TranslateSVG, CentralNotice, MassMessage and bunch of stuff in the translatewiki repository.

You can use the deprecation facilities provided by MediaWiki core, including the @deprecated tag and wfDeprecated() hard deprecation. If there are no known users of the code, it is okay to change it in backwards incompatible way without deprecation, unless it is explicitly marked as stable (See Stable interface policy). Code marked as stable should be hard-deprecated at least for one Pacote da Extensão de Línguas da MediaWiki (MLEB) release.

MediaWiki core version numbers are meaningless in the context of Translate, as Translate always supports multiple MediaWiki releases. Translate itself uses YYYY.MM style versioning (as part of MLEB). New classes and methods should be annotated with @since YYYY.MM tags.