Como criar pacotes de strings

Aprenda a criar pacotes de strings para seus plugins e temas para ajudar os usuários a traduzir conteúdo facilmente com o WPML.

Os pacotes de strings são grupos de strings “agrupadas” em um contexto específico. O objetivo deles é ajudar os usuários finais a traduzir o conteúdo com mais eficiência, eliminando a necessidade de traduzir cada string individualmente.

Por exemplo, veja como os usuários traduziriam campos personalizados de usuário, com e sem um pacote de strings:

Como você pode ver, os pacotes de strings simplificam o processo de tradução ao permitir que os usuários traduzam vários campos personalizados de usuário de uma só vez. Para oferecer aos seus usuários a melhor experiência de tradução, siga as etapas abaixo para criar seus próprios pacotes de strings.

1. Identifique o conteúdo traduzível

O primeiro passo é identificar o conteúdo que os usuários vão querer traduzir, como títulos, rótulos e conteúdo gerado pelo usuário.

2. Declare o tipo de pacote

Em seguida, você precisa declarar o tipo de pacote. Esta etapa ajuda o WPML a detectar quais pacotes de strings estão conectados aos plugins ativos e a traduzir apenas esses pacotes.

Para comparação, este filtro funciona para pacotes de strings exatamente como o filtro register_post_types funciona para tipos de post.

Para declarar um tipo de pacote, use o filtro wpml_active_string_package_kinds (abre em uma nova aba):

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;

} );

Definição de argumentos

title – o título do tipo, deve ser o mesmo que o tipo (kind) para os pacotes.
plural – a forma plural do título.
slug – o slug do tipo, deve ser o mesmo que o kind_slug para os pacotes.

3. Crie um pacote e registre as strings

Em seguida, você precisa criar um pacote e registrar as strings que ele vai agrupar usando o hook wpml_register_string (abre em uma nova aba):

$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' );

}

Definição de argumentos

$kind – o rótulo do namespace da entidade (por exemplo, Gravity Form).
$kind_slug – o slug do namespace da entidade (por exemplo, gravity-form). Se estiver ausente, será uma versão em slug do “tipo” (kind).
$name – o identificador único da entidade dentro do tipo, pode ser uma string (por exemplo, slug) ou um número inteiro (por exemplo, ID).
$title – o título da entidade dentro do tipo. É recomendado usar o título da entidade real.

Embora não seja necessário, você também pode incluir dois argumentos adicionais:
$edit_link – uma URL para editar o objeto.
$view_link – uma URL para visualizar o objeto.

4. Recupere as traduções

Por fim, para exibir as traduções no frontend, você precisa usar o hook wpml_translate_string (abre em uma nova aba):

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

}

Atualização e remoção de strings

Sempre que os usuários atualizam o conteúdo, o WPML precisa ser capaz de identificar as novas strings, bem como aquelas que foram removidas. Para notificar o WPML sobre essas alterações, envolva seu código de registro com duas funções:

• wpml_start_string_package_registration (abre em uma nova aba)
• wpml_delete_unused_package_strings (abre em uma nova aba)

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

Exclusão de pacotes de strings

Quando os usuários removem conteúdo, você também deve remover o pacote de strings associado a ele. Isso inclui todas as strings relacionadas, traduções e trabalhos de tradução. Ao fazer essa limpeza, você garante que o site permaneça eficiente, sem nenhum dado residual sobrecarregando o banco de dados.

Para remover um pacote de strings, use um hook em uma ação apropriada dentro do seu plugin ou tema e chame a função wpml_delete_package (abre em uma nova aba):

$userId = 123;

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

Recursos adicionais

• Arquivo de configuração de idioma do WPML – um guia sobre o uso do wpml-config.xml, o arquivo que indica quais textos o WPML deve traduzir em plugins e temas.
• Multilingual Tools – uma ferramenta para testar suas definições de configuração e confirmar a compatibilidade com o WPML.