Cómo crear paquetes de cadenas

Aprenda a crear paquetes de cadenas para sus plugins y temas para ayudar a los usuarios a traducir contenido fácilmente con WPML.

Los paquetes de cadenas son grupos de cadenas «empaquetadas» en un contexto específico. Su propósito es ayudar a los usuarios finales a traducir el contenido de forma más eficiente al eliminar la necesidad de traducir cada cadena individualmente.

Por ejemplo, así es como los usuarios traducirían los campos personalizados de usuario, con y sin un paquete de cadenas:

Sin un paquete de cadenas

Los usuarios necesitan traducir las cadenas una por una, sin la opción de traducción automática.

Con un paquete de cadenas

Los usuarios pueden traducir múltiples cadenas de una sola vez, con la opción de traducción automática.

Como puede ver, los paquetes de cadenas simplifican el proceso de traducción al permitir que los usuarios traduzcan múltiples campos personalizados de usuario a la vez. Para ofrecer a sus usuarios la mejor experiencia de traducción, siga los pasos a continuación para crear sus propios paquetes de cadenas.

1. Identifique el contenido traducible

El primer paso es identificar el contenido que los usuarios querrán traducir, como títulos, etiquetas y contenido generado por el usuario.

2. Declare el tipo de paquete

A continuación, necesita declarar el tipo de su paquete. Este paso ayuda a WPML a detectar qué paquetes de cadenas están conectados a plugins activos y a traducir solo esos paquetes.

A modo de comparación, este filtro funciona para los paquetes de cadenas de la misma manera que el filtro register_post_types funciona para los tipos de contenido.

Para declarar un tipo de paquete, utilice el filtro 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;

} );

3. Cree un paquete y registre las cadenas

A continuación, necesita crear un paquete y registrar las cadenas que va a agrupar utilizando el 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' );

}

4. Recupere las traducciones

Finalmente, para mostrar las traducciones en el front-end, necesita utilizar el 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 );

}

Actualizar y eliminar cadenas

Cada vez que los usuarios actualizan el contenido, WPML necesita poder identificar las nuevas cadenas, así como las que se eliminaron. Para notificar a WPML de estos cambios, envuelva su código de registro con dos funciones:

• 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 );

Eliminar paquetes de cadenas

Cuando los usuarios eliminan contenido, también debe eliminar su paquete de cadenas asociado. Esto incluye todas las cadenas, traducciones y trabajos de traducción relacionados. Al hacer esta limpieza, se asegura de que el sitio siga siendo eficiente sin que queden datos sobrantes que sobrecarguen la base de datos.

Para eliminar un paquete de cadenas, utilice un hook en una acción adecuada dentro de su plugin o tema y llame a la función wpml_delete_package:

$userId = 123;

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

Recursos adicionales

• Archivo de configuración de idiomas de WPML – una guía sobre el uso de wpml-config.xml, el archivo que indica qué textos debe traducir WPML en los plugins y temas.
• Herramientas multilingües – una herramienta para probar su configuración y confirmar la compatibilidad con WPML.