Download - WordPress Plugin Localization
May 22, 2011
Presented at WordCamp Raleigh
By Ronald Huereca
Wo r d P r e s s P l u g i n L o c a l i z a t i o n
Twitter: @ronalfy
Slides and code available at: http://ithem.es/localize
1
Plugin developer at iThemes (the
creators of Builder and BackupBuddy)
Author of the book WordPress and
Ajax
Plugin author of Ajax Edit Comments
Karaoke singer, gamer, and Vodka
drinker (sometimes at the same time)
A b o u t R o n a l d H u e r e c a
2
Allows your strings to be translated
into multiple languages
Provides a framework to format your
strings in a translatable way
W h a t i s L o c a l i z a t i o n ( a k a , I n t e r n a t i o n a l i z a t i o n ) ?
3
Your plugins or themes can be
translated by others
Your audience isn’t limited by one
locale or language
W h a t a r e t h e b e n e f i t s o f L o c a l i z a t i o n ?
4
S o w h a t d o e s l o c a l i z a t i o n l o o k l i k e ?
5
These strings are very sad :(
<div class='wrap'>! <h2>My Plugin Settings</h2>! <div class='updated'><p>Plugin Settings have been saved.</p></div></div>
E x a m p l e : U n - l o c a l i z e d s t r i n g s : (
6
These strings are very happy :-)
<div class='wrap'>! <h2><?php _e( 'My Plugin Settings', 'DOMAIN' ); ?></h2>! <div class='updated'><p><?php _e( 'Plugin Settings have been saved.', 'DOMAIN' ); ?></p></div></div>
E x a m p l e : L o c a l i z e d s t r i n g s : - )
7
Use the WordPress ‘init’ action
Function: load_plugin_textdomain (for
plugins)
Function: load_theme_textdomain (for
themes)
H o w t o e n a b l e l o c a l i z a t i o n f o r a p l u g i n ?
8
Simple, simple, simple...
<?php//Plugin header goes hereadd_action( 'init', 'pb_msp_init' );function pb_msp_init() {! //Admin menu! add_action( 'admin_menu', 'pb_msp_menu' );! //Assuming you have a languages folder in your plugin - Typically run within the 'init' action! load_plugin_textdomain( 'unique_domain', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' ); } //end pb_msp_init//More functions?>
E n a b l i n g L o c a l i z a t i o n f o r a P l u g i n
9
L e t ’s d o s o m e b a s i c l o c a l i z a t i o n
10
Returns a localized string - domain should be unique
<?php! echo __( 'Translate me!', 'unique_domain' ); ! //Do stuff with localized string here ?>
_ _ ( ‘ s t r i n g ’ , ‘ d o m a i n ’ )
11
Echos a localized string
<?php! _e( 'Translate me!', 'unique_domain' );! //Output is: Translate Me!?>
_ e ( ‘ s t r i n g ’ , ‘ d o m a i n ’ )
12
F o r m o s t c a s e s , _ e a n d _ _ a r e a l l y o u ’ l l e v e r c a r e
a b o u t
13
B u t w h a t i f y o u h a v e s i n g u l a r a n d p l u r a l f o r m s o f
a s t r i n g ?
14
F o r e x a m p l e : 1 c o m m e n t v s . 2 c o m m e n t s
15
Provide a singular string
Provide a plural string
Provide a count integer (e.g., 2 )
L e t ’s u s e t h e _ n ( ) f u n c t i o n
16
Returns a singular or plural form of a string
<?php! $total_count = 1;! if ( $total_count > 1 || $total_count == 0 ) $count = 2;! else $count = 1;! printf( _n( 'You have voted %d time', 'You have voted %d times', $count, 'unique_domain' ), $total_count );! //Output is: You have voted 1 time?>
_ n ( ‘ s i n g u l a r ’ , ‘ p l u r a l ’ ,$ c o u n t , ‘ d o m a i n ’ )
17
Context provides... context
How many ways can you interpret blue
(i.e., feeling blue or literally being blue)
W h a t a b o u t c o n t e x t ?
18
It helps your translators figure out
what the string is for
It’ll also make you think, should I use a
different phrase or word?
T h e _ x f u n c t i o n h e l p s p r o v i d e c o n t e x t
19
Returns a string in a specific context
<?php! echo _x( 'I am blue today.', 'noun', 'unique_domain' );! //You are literally blue ! echo _x( 'I am blue today.', 'adjective', 'unique_domain' );! //You are feeling blue (i.e., depressed) today?>
_ x ( ‘ s t r i n g ’ , ‘ c o n t e x t ’ , ‘ d o m a i n ’ )
20
W h a t a b o u t l o c a l i z i n g s t r i n g s i n J a v a S c r i p t ?
21
W h y w o u l d y o u e v e r w a n t t o l o c a l i z e s t r i n g s i n
J a v a S c r i p t ?
22
W h y t h e h e l l n o t ?
23
Queue your script like normal
(wp_enqueue_script)
Provide localization (via
wp_localize_script)
Update your scripts to use it
L o c a l i z i n g J a v a S c r i p t
24
Outputs a JavaScript object with localized variables
<?php! wp_enqueue_script( 'my_handler', get_stylesheet_directory_uri() . '/my_script.js', array( 'jquery' ), '1.0.0', false );! wp_localize_script( 'my_handler', 'my_script_object', array( 'text' => __( 'Localization is absolutely awesome', 'unique_domain' ) ) ); ?>
w p _ l o c a l i z e _ s c r i p t ( ‘ h a n d l e r ’ , ‘ o b j e c t _ n a m e ’ , $ l i 0 n )
25
Access the localized variable in JavaScript file my_script.js
jQuery(document).ready(function( $ ) {! alert( my_script_object.text );});
w p _ l o c a l i z e _ s c r i p t - C o n t i n u e d
26
T h e r e a r e a t o n o f h e l p e r f u n c t i o n s
27
__( ‘string’, ‘domain’ ) - Returns a localized string
_e( ‘string’, ‘domain’ ) - Echos a localized string
_n( ‘singular’, ‘plural’, $count, ‘domain’ ) - Returns a singular or plural
form of a string
_x( ‘string’, ‘context’, ‘domain’ ) - Returns a string in a context (context
can be anything really, but it helps give the translators an idea of what
you’re going for)
esc_html_e or esc_html__ (works like __ and _e, but returns
encoded text)
esc_attr_e or esc_attr__ (works for encoding attribute values)
wp_localize_script - Helper function for localizing JavaScript strings
L o c a l i z a t i o n F u n c t i o n s
28
_nx( ‘singular’, ‘plural’, $number, ‘context’, ‘domain’ ) - Combines the _n
and _x functions
_esc_attr_x( ‘string’, ‘context’, ‘domain’ ) - Like the esc_attr__
function, but with context
_esc_html_x( ‘string’, ‘context’, ‘domain’ ) - Like the esc_html__
function, but with context
_n_noop( ‘singular’, ‘plural’ ) - Provide _n strings for translation, but
will not be translated in the output (yet)
_nx_noop( ‘singular’, ‘plural’, ‘context’ ) - Provide _nx strings for
translation, but will not be translated in the output (yet)
translate_nooped_plural ( $noop_output, $number, ‘domain’ ) - Take
the results from _n_noop and _nx_noop and translate
E v e n m o r e . . .
29
sprintf( ‘string format’, $arg1, $arg2, etc... ) - Returns a formatted string
printf( ‘string format’ $arg1, $arg2, etc...) - Prints a formatted string
A n d s o m e h e l p e r f u n c t i o n s
30
H o w A b o u t a V i d e o D e m o n s t r a t i n g L o c a l i z a t i o n ?
31
H o w A b o u t a V i d e o D e m o n s t r a t i n g L o c a l i z a t i o n ?
31
Release a useful plugin that is localization ready
Make sure translators can contact you
The translators will come to you
Package their “.mo” file with future releases
Keep track of your translators and notify them before any
major updates (some translators can act as beta testers)
H o w t o G e t Tr a n s l a t o r s ?
32
Try to minimize da slang, ya know?
Limit jargon and acronomese FTW!
Translate sentences and paragraphs using sprintf or printf
to provide context
Avoid loooooong portions of translatable text - Split at
paragraphs or sentences
Avoid translating single words, and if you do, provide
context (_x function)
Avoid beginning or ending your string with whitespace
Try translating some of your own work - Even if it’s not
going in the final product, it’ll help you see what the
translators see
H o w t o H e l p Tr a n s l a t o r s
33
Use Poedit with the path and keywords (ewwwww, and way too
advanced - Would require another presentation)
With Poedit, just generate the “po” file and rename to “pot”. At least
that part is simple.
Use the WordPress Repo to do it (yay!!!)
H o w t o G e n e r a t e P O T F i l e s
34
Wo r d P r e s s R e p o F T W ! ! !
Make sure you’re logged in
Get your POT
35
< ? p h p _ e ( ‘ C o n c l u s i o n ’ ) ; ? >
Localization is super easy
Localization can increase your plugin audience
The WordPress Plugin Repo is ideal for generating
“pot” files. Poedit has issues.
36
< ? p h p e c h o _ _ ( “Ques t ions? ” ) ; ? >
Slides and code available at: http://ithem.es/localize
37
M o r e c o d e e x a m p l e s . . .
38
Returns a formatted string
<?php//%s is for a string placeholder, %d is for an integer (there's a lot more of these)echo sprintf( 'My name is %s and I am %d years old', 'Ronald', 29 );//Output is My name is Ronald and I am 29 years old //Reuse the same string over againecho sprintf( 'My name is %1$s and here I am again %1$s and I am %d years old', 'Ronald', 29 );//Output is My name is Ronald and here I am again Ronald and I am 29 years old?>
s p r i n t f ( ‘ s t r i n g ’ , [ a r g 1 , a r g 2 , e t c . . . ] )
39
Prints a formatted string
<?php//%s is for a string placeholder, %d is for an integer (there's a lot more of these)printf( 'My name is %s and I am %d years old', 'Ronald', 29 );//Output is My name is Ronald and I am 29 years old //Reuse the same string over againprintf( 'My name is %1$s and here I am again %1$s and I am %d years old', 'Ronald', 29 );//Output is My name is Ronald and here I am again Ronald and I am 29 years old?>
p r i n t f ( ‘ s t r i n g ’ , [ a r g 1 , a r g 2 , e t c . . . ] )
40
sprintf allows you to keep strings in context without concatenation
<?php! $total_count = 100; //retrieved from somewhere! $my_localized_string = sprintf( __( 'You have voted %d times', 'unique_domain' ), $total_count );! echo $my_localized_string;! //Output is: You have voted 100 times ?>
_ _ a n d s p r i n t f
41
Translates, encodes, and echoes
<div><?php esc_html_e( 'String to be outputted in HTML', 'unique_domain' ); ?></div>
e s c _ h t m l _ e ( ‘ s t r i n g ’ , ‘ d o m a i n ’ )
42
Translates, encodes, and returns
<?php! $dynamic_string = 'Tigerblood'; ?><div><?php printf( esc_html__( 'I drink %s', 'unique_domain' ), $dynamic_string ); ?></div>
e s c _ h t m l _ _ ( ‘ s t r i n g ’ , ‘ d o m a i n ’ )
43
Translates, encodes, and echoes
<a href='http://pluginbuddy.com' title='<?php esc_attr_e( 'PluginBuddy - The Creators of BackupBuddy', 'unique_domain' ); ?>'>PluginBuddy</a>
e s c _ a t t r _ e ( ‘ s t r i n g ’ , ‘ d o m a i n ’ )
44
Translates, encodes, and returns
<a href='http://pluginbuddy.com' title='<?php printf( esc_attr__( '%s - The Creators of %s', 'unique_domain' ), 'PluginBuddy', 'BackupBuddy' ); ?>'>PluginBuddy</a>
e s c _ a t t r _ _ ( ‘ s t r i n g ’ , ‘ d o m a i n ’ )
45
Combine printf and __ for a _e equivalent with formatting
<?php! printf( __( 'You have voted %d times', 'unique_domain' ), $total_count );! //Output is: You have voted 100 times?>
_ e e q u i v a l e n t w i t h p r i n t f a n d _ _
46