This document provides guidance on creating multilingual WordPress plugins and themes, emphasizing the importance of internationalization (i18n) and localization (l10n). It outlines necessary steps for making code translatable, such as using unique text domains and employing various translation functions, alongside best practices and potential challenges. The document also highlights tools available for translation and encourages developers to enhance their reach by accommodating non-English speaking users.

1. How to Make Multilingual
Plugins and Themes
John P Bloch ● 2016-02-20 ● WordCamp Miami

2. About Me
John P Bloch
Lead Web Engineer at 10up
10up is hiring
Tell them I sent you
Seriously, we’re always hiring
@johnpbloch
john.bloch@10up.com

3. Assumptions
& Definitions

4. Assumptions
• You can write PHP
• You are writing plugins or themes for distribution on the
wordpress.org repositories

5. Definitions
Internationalization
The process of making your
code translatable at all.
Abbreviated as i18n
Localization
The process of using translated
text in internationalized code.
Abbreviated as l10n

6. Definitions
Internationalization
The process of making your
code translatable at all.
Abbreviated as i18n
Localization
The process of using translated
text in internationalized code.
Abbreviated as l10n

7. Why should you care?

8. Why should you care?
• Empathy
• More than half of all new WordPress installations are in languages
other than English

11. Why should you care?
• Empathy
• Grow your potential user-base
• Potentially make more money
• Make more of an impact in the world

12. How to Internationalize Code

13. Text Domains
A text domain is a namespace for your code’s translations
Text domains need to be unique within plugins or themes
Use your plugin or theme slug

14. Text Domains – Loading Themes
load_theme_textdomain(
$textdomain,
$path // where your translations are
)
Run on after_setup_theme action
$path needs to be an absolute path

15. load_plugin_textdomain(
$textdomain,
false, // deprecated
$path // where translation files are
)
Run on plugins_loaded action
$path is relative to wp-content/plugins
Text Domains – Loading Plugins

16. Plugin and Theme Headers
Plugins and themes have two
special headers:
Text Domain
Domain Path

17. Basic Translation Functions
__( $text, $textdomain )
_e( $text, $textdomain )
_n(
$singular,
$plural,
$count,
$textdomain
)

18. Basic Translation Functions
$draft_count = get_my_drafts_count();
printf( _n(
'I have one draft.',
'I have %s drafts.',
$draft_count,
'my-textdomain'
), $draft_count );

19. Basic Translation Functions
$draft_count = get_my_drafts_count();
if( 1 === $draft_count ) {
_e( 'I have one post.', 'my-textdomain' );
} else {
printf( __(
'I have %s drafts.',
'my-textdomain'
), $draft_count );
}

20. Basic Translation Functions
_x( $text, $context, $textdomain )
_ex( $text, $context, $textdomain )
_nx(
$singular,
$plural,
$count,
$context,
$textdomain
)

21. Basic Translation Functions
You can also leave longer comments for the translators
printf(
/* translators: The placeholder is the
current user’s first name */
__( 'Hello, %s!', 'my-textdomain' ),
$current_user->first_name
);

22. Advanced Translation Functions
number_format_i18n(
$number,
$decimals = 0
)
1234567.89
1,234,567.89
1.234.567,89

23. Advanced Translation Functions
date_i18n(
$format,
$timestamp = false,
$gmt = false
)
'F j Y'
'February 20 2016'
'Febbraio 20 2016'

24. Advanced Translation Functions
Homework
Look up these translation
functions:
wp_localize_script()
esc_html__()
esc_html_e()
esc_html_x()
esc_attr__()
esc_attr_e()
esc_attr_x()

25. Final Steps

26. Final Steps
• Generate .pot file
• Official repositories provide web tools
• Publish .pot file
• Usually packaged with plugin or theme in the languages directory
• Add translation files to your plugin or theme
• Or don’t. Plugins have language packs now.

27. Gotchas

28. Gotchas
• Line breaks
• Empty strings
• Formatted strings vs. interpolation

29. _e( "You live in $state", 'my-plugin' );
#: my-plugin.php:23
msgid "You live in $state"
msgstr ""
$state = 'Florida';
// Lookup is "You live in Florida"

30. printf(
__( 'You live in %s', 'my-plugin' ),
$state
);

31. Gotchas
• Line breaks
• Empty strings
• Formatted strings vs. interpolation
• Word order and position

32. printf(
__( 'Hi %s, you live in %s', 'my-plugin' ),
$user_name, $state
);

33. printf(
__(
'Hi %1$s, you live in %2$s',
'my-plugin‘
),
$user_name, $state
);

34. Best Practices

35. Best Practices
• Use decent English style
• Avoid slang and abbreviations
• Keep text together
• Break at paragraphs
• Use formatted strings instead of
concatenation
• Translate phrases not words
• No unnecessary HTML
• Make no assumptions about
the translated text
• Length
• Word order
• Direction
• Punctuation
• Avoid translating URLs that
don’t have alternate
languages available

36. Tools
• Pig Latin (http://w.org/plugins/piglatin/)
• WP i18n Tools (develop.svn.wordpress.org/trunk/tools/i18n/)
• PoEdit (https://poedit.net/)
• GlotPress (http://blog.glotpress.org/)
• Translate WordPress (https://translate.wordpress.org)

37. Questions?
Twitter: @johnpbloch
Website: https://johnpbloch.com
Email: john.bloch@10up.com