l10n and i18n on Common APIs Handbook

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)

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

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 Javascript support for i18n introduced last year. This didn’t make it to the Docs yet:

What we could do

Here is my suggestion on how to organize this:

  1. Create an “Internationalization API” page on the Commons APIs Handbook with content from the current Codex page and the “How to Internationalize your theme/plugin” 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 core
  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