This is a more detailed explanation of what I have in mind for Step 5 in this post.

Much of the following is just notes to myself, so I don't forget; but comments on any part are welcome!

i18n documentation

This will mainly outline the rules we're using to create unique key names. It might also be a good idea to run through the procedure in a tutorial fashion, giving examples of the following steps:

How to extract a string with an app.trans call ... (Will this work for the backend as well?)
How to give each string a unique key name
- Prefixes: Indicate location; use existing locations if possible. How/when to create a new location.
- Suffixes: Indicate how the string is used. Choose from this list of officially approved suffixes.
- Roots: Keep descriptive. Submit and dismiss buttons are special cases. Optional in a few cases
How to reference reused and global strings
- Referencing reused and global strings from the core is okay, and generally future-proof
- Strings from extensions should not be referenced
- Referencing and extraction of reused strings can be saved for cleanup

If necessary, we can also include a reference to other i18n considerations, such as making sure that proper context is provided for things like pluralization and gender. (EDIT: The existing "Localization" page makes reference to pluralization, but it seems to be directed more at translators then at devs. A more goal-oriented presentation may be good for both sides.)

This information can be included in the documentation under the heading "Internationalization". Perhaps it should be listed after "Extending the Client". Would that be a good place for it?

(EDIT: We can replace the "Localization" page with an "Internationalization" page aimed specifically at devs, and move the purely localization-related information to a page of the same name, as described below. The question here is: Will one page be enough to cover all the i18n information that devs will need?)

l10n documentation

This will cover some of the same territory as the i18n specification, but slanted for translators rather than devs.

How to navigate the YML file and translate strings
How to replace a reference with a string, or add a new reused string
What to do when replacing a reference isn't enough

In addition, it would be a good idea to start with creation of the extension skeleton. Yes, I know that information is already there! But I think the way the docs are currently organized may be one reason we've been seeing problems caused by people basing their work on the French language pack. Translators aren't naturally inclined to think of language packs as extensions, so they won't even bother to read anything other than the "Localization" page.

We can head off some problems by creating a separate section below "Building Extensions". We can call it:

Translating Flarum
- Introduction ... (Defining the language pack as a special kind of extension)
- Getting Started ... (Creating the skeleton, setting the locale manually, etc.)
- Localization ... (All the stuff in the three bullet points above)
- Leveraging YAML ... (How to do things like pluralization and genderization)
- Distribution ... (How to make a language pack available to others)
- Support ... (How to support a language pack, with reference to flarum.today)

I'm not sure all of the above are necessary, but it's worth thinking about these docs from the viewpoint that not all translators will be able to follow documents intended for developers (assuming they even read them).

Installing Languages

We've thrown together some language pack installation instructions that are still pending approval. It might be a good idea to prettify these instructions (with some screenshots, perhaps? Probably don't need to go that far...) and put them in the docs pages. They could be titled "Adding Languages" (or something like that) and listed right under "Installation" in the sidebar. (Would an "Extensions" page be a good idea as well? To cover extension installation?)

Cleanup

Once the above things are taken care of, the following should also be done:

Modify the "How do I translate..." item in the FAQ to reference the new l10n documentation.
Modify the "Localization" link in the Packaging docs to refer to the new i18n documentation.

It might also be a good idea to post in the forums along the way to alert people to the new docs.

Conclusion

By splitting our language pack-related documentation up into these three categories, we make it easier for devs, translators, and admins to find the information they need. It should cut down quite a bit on support requests.

I stuck this in "Staff" for the time being, but if everyone thinks it is a good idea, we can move it to "Dev > i18n" so other interested parties can see it (and hopefully participate).

Any comments? Ideas? Further praise for my "under construction" writing technique? 😉