It's great to see someone working on this. However, I think theme localization could probably be either a built feature or a third party plugin.

I don't intend to add any more builtin extensions. The only reason search is a plugin is because it used to be a builtin feature which some people did not want to use. So we broke it out into a plugin, but included it by default to maintain backward compatibility while providing users a mechanism to disable it. l10n is very different. First of all, it has not yet been supported so we break nothing by not including it by default. However, I am concerned that if the templates contain translation strings (such as {{ _('nav.previous') }}), then we will always need l10n. In that case, it should be a built-in feature rather than a plugin.

To be clear, this should only cover translations of the templates themselves, not translation of any page content. Translation of page content should only be provided by a third party plugin.

Thanks for your feedback!

I did pretty much the same but built-in. See last update.

For reference purposes, this PR is addressing step 1 of this comment on #211.

Also, so that we don't forget about it, it might make sense for plugings.search.lang to default to theme.locale if it is set.

Beside documentation and your point about plugings.search.lang, there's a small snippet of English text in mkdocs/contrib/search/templates/search/main.js ("No results found") I'm not sure how to localize. Should it be moved in a html file passed through Jinja?

there's a small snippet of English text in mkdocs/contrib/search/templates/search/main.js ("No results found") I'm not sure how to localize. Should it be moved in a html file passed through Jinja?

I suppose that should be defined in the template. Then, for backward compatibility, the script should only redefine it if it is not defined in the template.

I finally had an opportunity to take a closer look at this. Looks good. However, the work is not done yet. At a minimum we need to do the following work:

• Resolve the existing merge conflict.
• Update the readthedocs theme to support translations (as has already been done with the mkdocs theme).
• List babel in the requirements files (in addition to setup.py).
• Document everything. We need to document things for users, theme devs, and translators; presumably separately.
• Work out the development workflow and possibly develop scripts/sub-commands to automate it.

On the last point, it appears that the following pieces are required to maintaining translations:

1. Each theme should have a PO template, which is the "extracted" file babel generates when it scans the source. Basically it is a PO file with the translations all blank (this file is missing from the PR at this time). Any time a theme dev updates a theme in such a way that the translatable strings are changed, the PO template needs to be updated. There are a couple ways we could do this:

   1. The file could be updated each time a change is committed to a theme template (either manually or automatically). In this case, the file would be stored in the repo somewhere. Where?

   2. The file could be generated each time it is needed by a translator using a provided script.

2. Each theme should also have a collection of translations, one per supported locale. Each translation is composed of the following pieces:

   1. A PO file, which is where the translations are maintained. To start a new locale, a translator would copy the PO template to a new locale subdirectory and then define the translations in the new PO file. After an update to the PO Template (by the theme dev as described above), a translator would diff the PO template against the PO file to determine which translations need to be added/updated and then make those updates/additions. We might want to automate both of those. Or explore third-party services that automate this for us.

      As a point of clarification, the existing PO file included in the PR is not a PO template, but an English locale PO file. Notice that the header (copyright notice etc) is not filed out in that file. The PO template should have that stuff filled out, but have the actual translations be blank. That way when PO files are created based on the template, they will also have the header filled out properly without requiring the translator to worry about that.

   2. A MO file is a compiled PO file and is used by MkDocs to build the site. There are multiple possible approaches here.

      a. We could require the translator to (re)generate the MO file before pushing up a PR.
      b. We could automate (re)generation of a MO file when a PO file is committed/merged.
      c. The MkDocs' release manager could (re)generate MO files when preparing a release.
      d. We could generate a MO file on each build (and test run?) of MkDocs (current behavior of this PR, if I undertstand correctly).

      In the first three of those options (a, b, c), the PO files would not be included in the release as we would have pregenerated MO files which would be included. However in the last option (d), we would include the PO files in the release, but not any MO files as they would be generated on the fly. Given the small size of the PO files, I'm not terribly worried about saving time by pregenerating the MO files. I think the solution we go with will depend on which is easier to implement/maintain.

@anlau Are you still working on this?

Not at the moment. Feel free to use the code from this PR.

Closing this as it was completed in #2299.