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