This post is a starting point to discuss how we can organize the documentation around Internationalization and Localization on the new Common APIs Handbook.

Common APIs Handbook is the new home for documentation on APIs used across WordPress that is not specific to themes, plugins or any other component. There you will find docs on Options API, Shortcode API, etc. (Note that content is still being migrated so there might be incomplete pages).

This should also be the home for the i18n and l10n documentation. So let’s see how this could look:

Current documentation

Here is a list of the current documentation on this topic we have (and that I could found)

• Main page on Codex (top result on Google search): I18n for WordPress developers

And then you have, at the top of that page, a link to documentation on both new Themes and Plugins Handbooks.

• How to internationalize your plugin
• Plugin localization
• How to internationalize your theme
• Theme localization

You will notice that we have duplicated content on these pages. “How to internationalize…�? pages are very similar, with small differences in how to initialize text domains and where to save the files. “Localization�? pages are pretty much the same.

Finally, we have the documentation on the new JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. support for i18n introduced last year. This didn’t make it to the Docs yet:

• Post on make.wordpress.org on javascript i18n support
• External post by Pascal on javascript i18n support

What we could do

Here is my suggestion on how to organize this:

1. Create an “Internationalization APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.�? page on the Commons APIs Handbook with content from the current Codex page and the “How to Internationalize your theme/pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party�? pages.
   1. These pages already have the same content
   2. Make sure to make it generic, in a way it works for themes, plugins, and the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.
2. Redirect Codex page to this newly created page
3. Edit “How to Internationalize your theme/plugin�? pages, leaving only plugins/themes specific information, and then linking to the “Internationalization API�? page for general guidelines
4. Add to the “Internationalization API�? page the section about i18n support in javascript. If we have permission, Pascal’s post could be incorporated.
5. Finally, we have to find a home for the “Localization�? page. This is not properly an API, so maybe it could be an article on https://wordpress.org/support/ and all i18n pages could link to it