WordPress Plugin Localization

7,278 views

Published on

WordPress plugin localization is extremely simple. This presentation will show you how to localize a WordPress plugin and show you some pretty advanced functions for helping your translators.

Published in: Education, Technology, Business
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
7,278
On SlideShare
0
From Embeds
0
Number of Embeds
862
Actions
Shares
0
Downloads
38
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

WordPress Plugin Localization

  1. 1. WordPress PluginLocalization By Ronald Huereca Twitter: @ronalfy Presented at WordCamp Raleigh May 22, 2011 1
  2. 2. About Ronald Huereca 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) 2
  3. 3. What is Localization (aka,Internationalization)? Allows your strings to be translated into multiple languages Provides a framework to format your strings in a translatable way 3
  4. 4. What are the benefits ofLocalization? Your plugins or themes can be translated by others Your audience isn’t limited by one locale or language 4
  5. 5. So what does localization look like? 5
  6. 6. Example: Un-localizedstrings :(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> 6
  7. 7. Example: Localizedstrings :-)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> 7
  8. 8. How to enable localizationfor a plugin? Use the WordPress ‘init’ action Function: load_plugin_textdomain (for plugins) Function: load_theme_textdomain (for themes) 8
  9. 9. Enabling Localization for aPluginSimple, simple, simple... <?php //Plugin header goes here add_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 ?> 9
  10. 10. Let’s do some basic localization 10
  11. 11. __( ‘string’, ‘domain’ )Returns a localized string - domain should be unique <?php ! echo __( Translate me!, unique_domain ); ! //Do stuff with localized string here ?> 11
  12. 12. _e( ‘string’, ‘domain’ )Echos a localized string <?php ! _e( Translate me!, unique_domain ); ! //Output is: Translate Me! ?> 12
  13. 13. For most cases, _e and __ are all you’ll ever care about 13
  14. 14. But what if you havesingular and plural forms of a string? 14
  15. 15. For example: 1 comment vs. 2 comments 15
  16. 16. Let’s use the _n() function Provide a singular string Provide a plural string Provide a count integer (e.g., 2 ) 16
  17. 17. _n( ‘singular’, ‘plural’,$count, ‘domain’ )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 ?> 17
  18. 18. What about context? Context provides... context How many ways can you interpret blue (i.e., feeling blue or literally being blue) 18
  19. 19. The _x function helpsprovide context 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? 19
  20. 20. _x( ‘string’, ‘context’,‘domain’ )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 ?> 20
  21. 21. What about localizingstrings in JavaScript? 21
  22. 22. Why would you ever want to localize strings in JavaScript? 22
  23. 23. Why the hell not? 23
  24. 24. Localizing JavaScript Queue your script like normal (wp_enqueue_script) Provide localization (via wp_localize_script) Update your scripts to use it 24
  25. 25. wp_localize_script( ‘handler’,‘object_name’, $li0n )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 ) ) ); ?> 25
  26. 26. wp_localize_script - ContinuedAccess the localized variable in JavaScript file my_script.js jQuery(document).ready(function( $ ) { ! alert( my_script_object.text ); }); 26
  27. 27. There are a ton of helper functions 27
  28. 28. Localization Functions __( ‘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 28
  29. 29. Even more... _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 29
  30. 30. And some helper functions sprintf( ‘string format’, $arg1, $arg2, etc... ) - Returns a formatted string printf( ‘string format’ $arg1, $arg2, etc...) - Prints a formatted string 30
  31. 31. How About a Video DemonstratingLocalization? 31
  32. 32. How About a Video DemonstratingLocalization? 31
  33. 33. H o w t o G e t Tr a n s l a t o r s ? 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) 32
  34. 34. H o w t o H e l p Tr a n s l a t o r s 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 33
  35. 35. How to Generate POT Files 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!!!) 34
  36. 36. WordPress Repo FTW!!! Make sure you’re logged in Get your POT 35
  37. 37. <?php _e( ‘Conclusion’ ); ?> Localization is super easy Localization can increase your plugin audience The WordPress Plugin Repo is ideal for generating “pot” files. Poedit has issues. 36
  38. 38. <?php echo __( “Questions?” ); ?> 37
  39. 39. More code examples... 38
  40. 40. sprintf( ‘string’, [arg1,arg2,etc...] )Returns a formatted string <?php //%s is for a string placeholder, %d is for an integer (theres 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 again echo 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 ?> 39
  41. 41. printf( ‘string’, [arg1,arg2,etc...] )Prints a formatted string <?php //%s is for a string placeholder, %d is for an integer (theres 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 again printf( 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 ?> 40
  42. 42. __ and sprintfsprintf 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 ?> 41
  43. 43. esc_html_e( ‘string’,‘domain’ )Translates, encodes, and echoes <div><?php esc_html_e( String to be outputted in HTML, unique_domain ); ?></div> 42
  44. 44. esc_html__( ‘string’,‘domain’ )Translates, encodes, and returns <?php ! $dynamic_string = Tigerblood; ?> <div><?php printf( esc_html__( I drink %s, unique_domain ), $dynamic_string ); ?></div> 43
  45. 45. esc_attr_e( ‘string’,‘domain’ )Translates, encodes, and echoes <a href=http://pluginbuddy.com title=<?php esc_attr_e( PluginBuddy - The Creators of BackupBuddy, unique_domain ); ? >>PluginBuddy</a> 44
  46. 46. esc_attr__( ‘string’,‘domain’ )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> 45
  47. 47. _e equivalent with printfand __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 ?> 46

×