Aprenda a criar pacotes de strings para os 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 de usuário personalizados, com e sem um pacote de strings:
Sem um pacote de strings
Os usuários precisam traduzir as strings uma a uma, sem a opção de tradução automática.
Com um pacote de strings
Os usuários podem traduzir várias strings juntas de uma só vez, com a opção de tradução automática.
Como você pode ver, os pacotes de strings simplificam o processo de tradução ao permitir que os usuários traduzam vários campos de usuário personalizados de uma só vez. Para oferecer aos seus usuários a melhor experiência de tradução, siga os passos abaixo para criar seus próprios pacotes de strings.
Se você quiser ver a implementação completa do pacote de strings que abordamos nos passos abaixo, confira este repositório do GitHub que contém o plugin de teste que usamos.
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 do seu pacote. Este passo ajuda o WPML a detectar quais pacotes de strings estão conectados a plugins ativos e a traduzir apenas esses pacotes.
Para fins de comparação, este filtro funciona para pacotes de strings assim 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:
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 dos argumentos
title – o título do tipo, deve ser o mesmo que o 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:
$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 dos argumentos
$kind – o rótulo do namespace da entidade (ex.: Gravity Form).$kind_slug – o slug do namespace da entidade (ex.: gravity-form). Se estiver ausente, será uma versão em slug do “kind”.$name – o identificador único da entidade dentro do tipo, pode ser uma string (ex.: slug) ou um número inteiro (ex.: 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 – um URL para editar o objeto.$view_link – um URL para visualizar o objeto.
4. Recupere as traduções
Por fim, para exibir as traduções no front-end, você precisa usar o 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 );
}
Como atualizar e remover strings
Sempre que os usuários atualizarem 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:
$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 );
Como excluir pacotes de strings
Quando os usuários removerem um conteúdo, você também deve remover o pacote de strings associado a ele. Isso inclui todas as strings, traduções e trabalhos relacionados. Ao fazer essa limpeza, você garante que o site permaneça eficiente, sem nenhum dado restante 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:
$userId = 123; do_action( 'wpml_delete_package', $userId, FOO_USER_FIELD_PACKAGE_KIND_SLUG );
Recursos adicionais
- Arquivo de configuração de idiomas 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 as suas configurações e confirmar a compatibilidade com o WPML.