I18n & RTL support
In WordPress, Internationalization (i18n) and RTL (right-to-left) support ensure websites can be adapted for different languages and writing directions. i18n involves using translation functions like __() and _e() to allow themes and plugins to be translated easily. For RTL support, WordPress provides built-in handling of RTL stylesheets by automatically loading rtl.css files when the site’s language is set to an RTL language like Arabic or Hebrew. These practices make WordPress sites accessible and functional for a global audience, regardless of language or script direction.
Internationalization (i18n) in WordPress Block Development
Internationalization (i18n) refers to preparing your blocks for translation and cultural adaptation. This ensures that your blocks can be used by a global audience, regardless of language or writing system. WordPress has built-in support for i18n, making it easier to create blocks that are accessible to non-English speakers.
Use WordPress i18n Functions for All User-Facing Strings
Whenever your block contains any text that is visible to the end user, it should be prepared for translation using WordPress’s internationalization functions. These functions allow the text to be translated into other languages through .mo and .po files without modifying the code itself.
Key Functions in WordPress i18n for Blocks:
- __(): This is used to wrap simple strings that need to be translated. Example:
const myBlockTitle = __( 'My Custom Block', 'text-domain' );
- _x(): This function is similar to __(), but it also allows you to pass a context string to clarify the meaning of ambiguous terms.
const buttonLabel = _x( 'Save', 'button label', 'text-domain' );
- _n(): This is used for pluralization, enabling you to provide singular and plural versions of a string.
const message = _n( 'One comment', '%s comments', commentCount, 'text-domain' );
Example of Implementing i18n in a Gutenberg Block:
When you develop a Gutenberg block, you may have labels, button text, and placeholders that users see in the editor. Each of these needs to be translated.
import { __ } from '@wordpress/i18n';
registerBlockType( 'my-plugin/my-block', {
title: __( 'My Block', 'text-domain' ),
description: __( 'A block for custom content.', 'text-domain' ),
edit() {
return (
<div>
<p>{ __( 'Edit your content here.', 'text-domain' ) } </p>
</div>
);
},
save() {
return (
<div>
<p>{ __( 'Your custom content.', 'text-domain' ) }</p>
</div>
);
},
} );
Best Practices:
- Always use text domains that are unique to your plugin or theme. The text domain should match your plugin slug, so translations are properly mapped.
- Avoid hardcoding any user-facing text in your blocks. Always wrap them in i18n functions to ensure they can be translated by WordPress translators.
- Make sure your .pot file (Portable Object Template) is up to date with all translatable strings by using tools like `wp i18n make-pot` to extract strings from your code.
Consider Right-to-Left (RTL) Language Support
Right-to-left (RTL) language support is crucial when developing for languages like Arabic, Hebrew, and Persian. In RTL languages, content and user interfaces are mirrored from left to right. Therefore, your blocks and styles need to account for this shift in layout.
Here are few best practices to support RTL Languages.
1. Use WordPress’s RTL Support:
WordPress automatically provides RTL versions of styles if they are set up correctly. When you enqueue your block’s CSS, WordPress will load RTL-specific styles as long as they exist. If you use logical CSS properties (like margin-inline-start), WordPress will generate an RTL version automatically.
Example:
wp_register_style(
'my-block-editor-style',
plugins_url( 'editor.css', __FILE__ ),
array( 'wp-edit-blocks' ),
filemtime( plugin_dir_path( __FILE__ ) . 'editor.css' )
);
wp_style_add_data( 'my-block-editor-style', 'rtl', 'replace' );
2. Use Logical CSS Properties:
Instead of hardcoding left or right values, use CSS logical properties to make your block automatically adjust in RTL languages. For example, instead of `margin-left`, use `margin-inline-start`. This ensures that your margins and paddings are automatically mirrored in RTL environments.
.my-block {
padding-inline-start: 20px; /* Replaces padding-left */
text-align: start; /* Replaces text-align: left */
}
This approach ensures that the layout adapts to both LTR and RTL languages without the need for separate stylesheets.
3. Test Your Block in RTL Environments:
Once your block is developed, it’s essential to test it in an RTL language to ensure that the layout, text alignment, and other design elements display correctly. You can do this by switching your WordPress site’s language to an RTL language, such as Arabic or Hebrew.
Example of RTL-Supporting Styles:
Let’s say you have a Gutenberg block with custom CSS:
.my-block {
padding-left: 20px;
text-align: left;
}
To support RTL languages, you would modify it like this:
.my-block {
padding-inline-start: 20px; /* Replaces padding-left */
text-align: start; /* Replaces text-align: left */
}
If you need more control, you can provide a separate RTL stylesheet by adding styles like this:
/* RTL-specific styles */
html[dir="rtl"] .my-block {
padding-right: 20px;
text-align: right;
}
How to Identify Page Language for Improved Internationalization
When building blocks, especially those that rely on visual content, it’s important to be aware of the page’s language context. You should identify the language in use so that you can provide the best user experience possible. Here’s how this plays out:
- HTML `lang` Attribute: WordPress outputs the `lang` attribute for the current site language. This is important because it tells search engines and assistive technologies which language the page is using.
Example of an HTML tag with the `lang` attribute:
<html lang="en-US">
- CSS for Specific Languages: You can also use the lang attribute to target specific language styles. For example, if you want to change the text style for Arabic users, you can use the [lang=”ar”] selector:
[lang="ar"] .my-block {
font-family: 'Cairo', sans-serif;
}
Dynamic Language Adjustments: If your block content changes based on the user’s language (for example, offering different date formats or directionality), ensure that your block reads the `lang` attribute to adjust the content accordingly.
