{"id":126023,"date":"2019-10-31T16:13:56","date_gmt":"2019-10-31T16:13:56","guid":{"rendered":"https:\/\/developer.wordpress.org\/?post_type=apis-handbook&#038;p=126023"},"modified":"2023-11-27T18:43:17","modified_gmt":"2023-11-27T18:43:17","slug":"internationalization","status":"publish","type":"apis-handbook","link":"https:\/\/developer.wordpress.org\/apis\/internationalization\/","title":{"rendered":"Internationalization"},"content":{"rendered":"\n<h2 class=\"wp-block-heading\">What is internationalization?<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Internationalization is the process of developing your application in a way it can easily be translated into other languages. Internationalization is often abbreviated as <code>i18n<\/code> (because there are 18 letters between the letters i and n).<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Why is internationalization important?<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">WordPress is used all over the world, by people who speak many different languages. The strings in WordPress need to be coded in a special way so that they can be easily translated into other languages. As a developer, you may not be able to provide localization for all your users; however, a translator can successfully localize your code without needing to modify the source code itself. <\/p>\n\n\n\n<p class=\"wp-block-paragraph\">While making your code translatable is called Internationalization, the act of translating it and adapting the strings to a specific location is called <a href=\"https:\/\/developer.wordpress.org\/apis\/handbook\/internationalization\/localization\/\">Localization<\/a>. Read more about <a href=\"https:\/\/developer.wordpress.org\/apis\/handbook\/internationalization\/localization\/\">Localization in WordPress<\/a>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">The basics<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">In order to make a string translatable, you have to wrap the original strings in a call to one of the <a href=\"https:\/\/developer.wordpress.org\/apis\/handbook\/internationalization\/internationalization-functions\/\">WordPress i18n functions<\/a>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">For example, the PHP function <a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/_e\/\" rel=\"function\">_e()<\/a>  echoes a translatable string:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><pre class=\"wp-block-code\"><code lang=\"php\" class=\"language-php \"> _e('Edit post'); <\/code><\/pre><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">You will find code like this all over WordPress core files. However, if you are internationalizing a theme or a plugin, there is another argument that all i18n functions take called Text Domain.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Text Domains set the domain your plugin or theme translations belong. This assures there is no conflict between strings in plugins, themes, and the WordPress core.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">With a text-domain, the most basic call to a i18n function that will output a string would be like:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><pre class=\"wp-block-code\"><code lang=\"php\" class=\"language-php \"> _e('Edit movie', 'my-plugin'); <\/code><\/pre><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Setting up your plugin and theme to i18n<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Setting up i18n is slightly different for Plugins and Themes, therefore this information is detailed in each respective Handbook:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/developer.wordpress.org\/themes\/functionality\/internationalization\/\">How to internationalize your theme<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/developer.wordpress.org\/plugins\/internationalization\/how-to-internationalize-your-plugin\/\">How to internationalize your plugin<\/a><\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Internationalizing JavaScript<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Since WordPress 5.0 it&#8217;s possible to internationalize JavaScript files using the same set of i18n functions used in PHP. <\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In order to be able to use i18n functions in your JavaScript code, you have to declare <code>wp-i18n<\/code> as a dependency on your script when registering or enqueueing it. For example:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"php\" class=\"language-php\">wp_register_script(\n     'my-script',\n     plugins_url( 'js\/my-script.js', FILE ),\n     array( 'wp-i18n' ),\n     '0.0.1'\n );<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Now that you have added the dependency to your script, you can use i18n functions in it, however you still have to tell WordPress to load the translations. <\/p>\n\n\n\n<p class=\"wp-block-paragraph\">You do this by calling <code>wp_set_script_translations()<\/code>. This function takes three arguments: the registered\/enqueued script handle, the text domain, and optionally a path to the directory containing translation files. The latter is only needed if your plugin or theme is not hosted on WordPress.org, which provides these translation files automatically.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"php\" class=\"language-php\">wp_set_script_translations('my-script', 'my-plugin');<\/code><\/pre>\n\n\n\n<div class=\"wp-block-wporg-notice is-info-notice\">\n<div class=\"wp-block-wporg-notice__icon\"><\/div>\n<div class=\"wp-block-wporg-notice__content\">For better performance, always make sure to enqueue your scripts and load their translations only when they are really used.<\/div><\/div>\n\n\n\n\n<p class=\"wp-block-paragraph\">In your JavaScript code you will use i18n functions pretty much the same way you do in your PHP code:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"js\" class=\"language-js\">const { __, _x, _n, sprintf } = wp.i18n;\n\n\/\/ simple string\n__( 'Hello World', 'my-plugin' );\n\n\/\/ string with context\n_x( 'My Gutenberg block name', 'block name', 'my-plugin' );<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The available i18n for you to use in your JS code are (See internationalization functions for more details):<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/__\/\" rel=\"function\">__()<\/a> <\/li>\n\n\n\n<li> <a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/_x\/\" rel=\"function\">_x()<\/a> <\/li>\n\n\n\n<li> <a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/_n\/\" rel=\"function\">_n()<\/a> <\/li>\n\n\n\n<li> <a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/_nx\/\" rel=\"function\">_nx()<\/a> <\/li>\n\n\n\n<li> sprintf()<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Notice that the wp-i18n package also includes the <code>sprintf<\/code> function. This is very useful to internationalize strings that have variables in it. <\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Now refer to the Internationalization Guidelines to learn how to use all these functions and the best practices on writing your strings.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">\n<div class=\"wp-block-wporg-notice is-info-notice\">\n<div class=\"wp-block-wporg-notice__icon\"><\/div>\n<div class=\"wp-block-wporg-notice__content\"> If you are not hosting your plugin or theme on WordPress.org, you will need to create your translation files yourself. Check <a href=\"https:\/\/pascalbirchler.com\/internationalization-in-wordpress-5-0\/\">this post<\/a> out to learn how to do this.<\/div><\/div>\n<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Internationalizing JavaScript before WP 5.0<\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">Another way to internationalize your JavaScript files is to use the <a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/wp_localize_script\/\" rel=\"function\">wp_localize_script()<\/a>  function.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">With this function you can register translatable strings and have them available in your JavaScript to be used.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Please refer to the <a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/wp_localize_script\/\"><code>wp_localize_script<\/code>() reference<\/a> to learn how to use it.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Internationalization Guidelines<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Now that you are ready to internationalize your application, read through the <a href=\"https:\/\/developer.wordpress.org\/apis\/handbook\/internationalization\/internationalization-guidelines\/\">Internationalization Guidelines<\/a> and learn what each i18n function is for, how to use them, and the best practices when writing your strings.<\/p>\n","protected":false},"author":144759,"featured_media":0,"parent":0,"menu_order":30,"template":"","meta":{"footnotes":""},"class_list":["post-126023","apis-handbook","type-apis-handbook","status-publish","hentry","type-handbook"],"revision_note":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook\/126023","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook"}],"about":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/types\/apis-handbook"}],"author":[{"embeddable":true,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/users\/144759"}],"version-history":[{"count":11,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook\/126023\/revisions"}],"predecessor-version":[{"id":150284,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook\/126023\/revisions\/150284"}],"wp:attachment":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/media?parent=126023"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}