Comment créer des paquets de chaînes

Apprenez à 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 « regroupées » dans un contexte spécifique. Leur but est d’aider les utilisateurs finaux à traduire le contenu plus efficacement en éliminant le besoin de traduire chaque chaîne individuellement.

Par exemple, voici comment les utilisateurs traduiraient des champs d’utilisateur personnalisés, 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 d’utilisateur personnalisés à 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 le type de votre 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 exactement 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 (s'ouvre dans un nouvel onglet) :

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 (kind) 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

Ensuite, vous devez créer un paquet et enregistrer les chaînes qu’il va regrouper à l’aide du hook wpml_register_string (s'ouvre dans un nouvel onglet) :

$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 « kind » (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 (s'ouvre dans un nouvel onglet) :

$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

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

• wpml_start_string_package_registration (s'ouvre dans un nouvel onglet)
• wpml_delete_unused_package_strings (s'ouvre dans un nouvel onglet)

$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, traductions et tâches de traduction associées. En effectuant ce nettoyage, vous vous assurez 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 de votre extension ou thème et appelez la fonction wpml_delete_package (s'ouvre dans un nouvel onglet) :

$userId = 123;

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

Ressources supplémentaires

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