Comment créer des paquets de chaînes

Découvrez comment créer des paquets de chaînes pour vos extensions et thèmes afin d’aider les utilisateurs à traduire facilement le contenu avec WPML.

Les paquets de chaînes sont des groupes de chaînes de texte « regroupées » dans un contexte spécifique. Leur but est d’aider les utilisateurs finaux à traduire le contenu plus efficacement en éliminant la nécessité de traduire chaque chaîne de texte individuellement.

Par exemple, voici comment les utilisateurs traduiraient des champs personnalisés d’utilisateur, avec et sans paquet de chaînes :

Comme vous pouvez le constater, les paquets de chaînes simplifient le processus de traduction en permettant aux utilisateurs de traduire plusieurs champs personnalisés d’utilisateur à la fois. Pour offrir à vos utilisateurs la meilleure expérience de traduction, suivez les étapes ci-dessous pour créer vos propres paquets de chaînes.

1. Identifiez le contenu traduisible

La première étape consiste à identifier le contenu que les utilisateurs voudront traduire, tel que les titres, les étiquettes et le contenu généré par les utilisateurs.

2. Déclarez le type de paquet

Ensuite, vous devez déclarer votre type de paquet. Cette étape aide WPML à détecter quels paquets de chaînes sont connectés aux extensions actives, et à ne traduire que ces paquets.

À titre de comparaison, ce filtre fonctionne pour les paquets de chaînes tout comme le filtre register_post_types fonctionne pour les types de publication.

Pour déclarer un type de paquet, utilisez le filtre wpml_active_string_package_kinds :

define( 'FOO_USER_FIELD_PACKAGE_KIND_TITLE', 'OTGS Foo User Fields' );

define( 'FOO_USER_FIELD_PACKAGE_KIND_SLUG', 'otgs-foo-user-fields' );

add_filter( 'wpml_active_string_package_kinds', function( $kinds ) {

   $kinds[ FOO_USER_FIELD_PACKAGE_KIND_SLUG ] = [

            'title'  => FOO_USER_FIELD_PACKAGE_KIND_TITLE,

            'slug'   => FOO_USER_FIELD_PACKAGE_KIND_SLUG,

            'plural' => FOO_USER_FIELD_PACKAGE_KIND_TITLE,

    ];

    return $kinds;

} );

Définition des arguments

title – le titre du type, doit être le même que le type pour les paquets.
plural – la forme plurielle du titre.
slug – le slug du type, doit être le même que le kind_slug pour les paquets.

3. Créez un paquet et enregistrez les chaînes de texte

Ensuite, vous devez créer un paquet et enregistrer les chaînes de texte qu’il va regrouper à l’aide du hook wpml_register_string :

$userId = 123;

$user   = get_user_by( 'id', $userId );

$package = [

    'kind'      => FOO_USER_FIELD_PACKAGE_KIND_TITLE, // The "namespace".

    'kind_slug' => FOO_USER_FIELD_PACKAGE_KIND_SLUG, // The "namespace" slug.

    'name'      => $userId, // Can be a string or an integer, but should be unique inside the "kind" namespace.

    'title'     => $user->display_name, // The title for the package entity inside the "kind" namespace.

];

$fooUserFields = get_option( 'otgs_foo_user_fields' );

foreach ( $fooUserFields as $fooUserField ) {

$fieldValue = get_user_meta( $userId, $fooUserField, true );

do_action( 'wpml_register_string', $fieldValue, sanitize_key( $fooUserField ), $package, $fooUserField, 'LINE' );

}

Définition des arguments

$kind – l’étiquette de l’espace de noms de l’entité (par ex., Gravity Form).
$kind_slug – le slug de l’espace de noms de l’entité (par ex., gravity-form). S’il est manquant, ce sera une version slug du « type ».
$name – l’identifiant unique de l’entité au sein du type, peut être une chaîne (par ex., un slug) ou un entier (par ex., un ID).
$title – le titre de l’entité au sein du type. Il est recommandé d’utiliser le titre de l’entité réelle.

Bien que ce ne soit pas nécessaire, vous pouvez également inclure deux arguments supplémentaires :
$edit_link – une URL pour modifier l’objet.
$view_link – une URL pour afficher l’objet.

4. Récupérez les traductions

Enfin, pour afficher les traductions sur l’interface publique, vous devez utiliser le hook wpml_translate_string :

$userId = 123;

$user   = get_user_by( 'id', $userId );

$package = [

        'kind'      => FOO_USER_FIELD_PACKAGE_KIND_TITLE, // The "namespace".

        'kind_slug' => FOO_USER_FIELD_PACKAGE_KIND_SLUG, // The "namespace" slug.

        'name'      => $userId, // Can be a string or an integer, but should be unique inside the "kind" namespace.

        'title'     => $user->display_name, // The title for the package entity inside the "kind" namespace.

];

$fooUserFields = get_option( 'otgs_foo_user_fields' );

$translatedFieldValues = [];

foreach ( $fooUserFields as $fooUserField ) {

    $fieldValue              = get_user_meta( $userId, $fooUserField, true );

    $translatedFieldValues[ $fooUserField ] = apply_filters( 'wpml_translate_string', $fieldValue, sanitize_key( $fooUserField ), $package );

}

Mettre à jour et supprimer des chaînes de texte

Chaque fois que les utilisateurs mettent à jour du contenu, WPML doit pouvoir identifier les nouvelles chaînes de texte, ainsi que celles qui ont été supprimées. Pour notifier WPML de ces modifications, enveloppez votre code d’enregistrement avec deux fonctions :

• wpml_start_string_package_registration
• wpml_delete_unused_package_strings

$userId = 123;

$package = [

        'kind'      => FOO_USER_FIELD_PACKAGE_KIND_TITLE, // The "namespace".

        'kind_slug' => FOO_USER_FIELD_PACKAGE_KIND_SLUG, // The "namespace" slug.

        'name'      => $userId, // Can be a string or an integer, but should be unique inside the "kind" namespace.

        // The 'title' key is not not required in the "translate" context.

];

do_action( 'wpml_start_string_package_registration', $package );

$fooUserFields = get_option( 'otgs_foo_user_fields' );

foreach ( $fooUserFields as $fooUserField ) {

    $fieldValue = get_user_meta( $userId, $fooUserField, true );

    do_action( 'wpml_register_string', $fieldValue, sanitize_key( $fooUserField ), $package, $fooUserField, 'LINE' );

}

do_action( 'wpml_delete_unused_package_strings',$package );

Supprimer des paquets de chaînes

Lorsque les utilisateurs suppriment du contenu, vous devez également supprimer son paquet de chaînes associé. Cela inclut toutes les chaînes de texte, traductions et tâches de traduction associées. En effectuant ce nettoyage, vous garantissez que le site reste performant sans aucune donnée résiduelle encombrant la base de données.

Pour supprimer un paquet de chaînes, utilisez un hook sur une action appropriée au sein de votre extension ou thème et appelez la fonction wpml_delete_package :

$userId = 123;

do_action( 'wpml_delete_package', $userId, FOO_USER_FIELD_PACKAGE_KIND_TITLE );

Ressources supplémentaires

• Fichier de configuration de langue WPML – un guide sur l’utilisation de wpml-config.xml, le fichier indiquant quels textes WPML doit traduire dans les extensions et les thèmes.
• Multilingual Tools – un outil pour tester votre configuration et confirmer la compatibilité avec WPML.