Aide:Extension:Translate/Guide du développeur
- Comment traduire
- Les bonnes pratiques
- Statistiques et rapports
- Assurance qualité
- États des groupes de messages
- Traductions hors-ligne
- Glossaire
Administrateurs de traduction
- Comment préparer une page à traduire
- Administration de la traduction des pages
- Traduction des éléments non structurés
- Gestion de groupe
- Renommer une page traductible
- Importer des traductions via CSV
- Travailler avec les paquets de messages
Administrateurs système et développeurs
L'extension Translate est une grosse extension avec des centaines de classes. Cette page donne les règles aux développeurs qui souhaitent travailler sur le code. Après avoir lu cette page et les documents liés, vous aurez une meilleure idée de l'organisation du code dans Translate et des conventions spéciales utilisées. Nous ne décrirons pas ici les règles générales du développement MediaWiki, ni les conventions de codage, ni la manière d'utiliser les outils comme Gerrit ou Phabricator. Vous êtes supposé les connaître et lorsqu'ils s'appliquent à Translate, il ne seront pas répétés ici.
L'extension Translate va subir plusieurs migrations importantes simultanément. Voici les migrations majeures en cours avec les détails du style préféré pour le nouveau code. Généralement lorsque vous modifiez du code existant il vaut mieux garder le style courant et faire les migrations de manière séparée. Vous êtes autorisés à faire de petits nettoyages quand vous modifiez le code.
Migrer un espace de noms
Actuellement nous migrons tout le code de Translate dans l'espace de noms \MediaWiki\Extension\Translate.
Tout le code de l'espace de noms est placé dans le répertoire src/.
Tous les nouveaux fichiers PHP doivent être dans un espace de noms approprié.
Voir Extension:Translate/Namespaces pour les règles concernant les espaces de noms disponibles prochainement.
Les espaces de noms sont organisés par domaine plutôt que par fonction.
Les abbréviations doivent être évitées dans le nom des espaces de noms ainsi que pour les classes.
Le code ancien se trouve à la racine du dépôt ainsi que dans divers sous-répertoires.
src/.
Séparer les tests d'intégration des tests unitaires
Auparavant, il n'y avait pas de distinction entre l'intégration et les essais unitaires.
Pour le nouveau code, les essais unitaires doivent être le type principal de tests.
Les tests unitaires sont mis dans le répertoire tests/phpunit/unit de l'espace de noms.
Il y a un Makefile dans ce répertoire pour exécuter facilement l'ensemble (ou une partie) des tests unitaires durant le développement.
Déclarations de type et commentaires
Tout nouveau code doit déclarer le type des paramètres et des valeurs renvoyées.
De plus, les types stricts doivent être activés en utilisant declare( strict_types = 1 );.
Grâce aux déclarations de type, la plupart des commentaires de fonctions et de méthodes deviennent redondants quand ils répètent le nom et le type des paramètres. N'ajoutez pas de documentation redondante à moins qu'elle apporte des informations. Un tel exemple serait de fournir des détails précis sur les types de tableaux comme :
class UserManager {
/** @return User[] */
public function getAllUsers(): array { ... }
}
Comme montré ci-dessus, pour les commentaires ayant une seule balise ou une ligne de description, utilisez également la syntaxe du commentaire sur une ligne.
: dans les déclarations du type de retour. Jusqu'à ce que cette norme soit mise en place, veuillez utiliser le style illustré : pas d'espace avant, une espace après.
Injection de la dépendance des constructeurs
Le nouveau code doit avoir toutes ses dépendances déclarées via le constructeur. Dans certains cas, cela n'est pas encore possible en raison du manque de support de ObjectFactory pour certains types de classes comme les scripts de tâche et ceux de maintenance. Pour ce nouveau code, placez toutes les dépendances sur le constructeur de la classe (ou le point d'accès principal de la classe) pour une migration facile vers l'injection de dépendance du constructeur à l'avenir.
execute, et non pas dans le constructeur.
Entête des fichiers
Pour le nouveau code nous avons choisi l'entête minimaliste suivante :
<?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 { ... }
}
Si vous souhaitez faire valoir vos droits d'auteur plus explicitement, vous pouvez (facultatif) également ajouter la balise @copyright.
Obsolescence et numéros de version
Lorsque vous modifiez le code de Translate de sorte à ce qu'il devienne incompatible avec le passé, vérifiez bien https://codesearch.wmcloud.org/search/ pour tous les utilisateurs du code. Les utilisateurs connus sont TwnMainPage, TranslateSVG, CentralNotice, MassMessage et une multitude dans le dépôt Translatewiki.
Vous pouvez utiliser les facilités de dépréciation fournies par le noyau MediaWiki, y compris la balise @deprecated et la dépréciation forcée wfDeprecated(). Si aucun utilisateur du code n'est connu, vous pouvez modifier ce code en le rendant incompatible arrière sans obsolescence, sauf s'il est marqué stable explicitement (voir les Règles des interfaces stables). Le code marqué comme étant stable doit noté dépréciation forcée au moins pour une version de Modules MediaWiki d'extension des langues (MLEB).
Les numéros de version du noyau MediaWiki n'ont pas de signification dans le contexte de Translate, car celui-ci prend toujours en charge plusieurs versions de MediaWiki. Translate lui même utilise le style de version AAAA.MM (comme partie de MLEB). Les nouvelles classes et méthodes doivent être annotées avec des balises @since AAAA.MM .