Docs: Improved introduction to i18n for Cog authors and Translators #6351
Conversation
github-actions
bot
added
Category: Core - i18n
|
Now I see the broken docs tests :-) That's what happens when I write too much asciidoc and markdown. Will put a new commit to fix in a second. |
…+fixed broken docs test!)
|
c685f9e pushed just now - it just fixes the double-backtick formatting needed for rst, rather than the single-backtick that I'm used to from asciidoc/markdown! I thought this looked somewhat better than the I don't intend to make any further commits at the moment -- so this is for your review/comments, etc. :-) |
Flame442
added
the
Type: Enhancement
Many thanks to @aikaterna for reviewing and suggesting typo fixes. Co-authored-by: aikaterna <20862007+aikaterna@users.noreply.github.com>
| The Red framework supports translations into different languages, making it easy | ||
| for translators to contribute new language files to the Red project, and to Cogs | ||
| that use the framework. The framework is based on the popular gettext format, |
There was a problem hiding this comment.
| The Red framework supports translations into different languages, making it easy | |
| for translators to contribute new language files to the Red project, and to Cogs | |
| that use the framework. The framework is based on the popular gettext format, | |
| Red supports an internationalization framework designed to allow users to | |
| translate user-facing strings to a contextually defined language. This | |
| framework is available for Cog Creators to use to define translations for the | |
| strings in their cogs. The framework is based on the popular gettext format, |
Just calling it "The red framework" in the first line is using an adjective without its noun. Splitting this sentence in two allows it to be explained in a bit more depth, while avoiding a run on.
| * ``.pot`` files are typically generated by the original author of the cog, and | ||
| contain the basic messages in en_US (the language Red is written in), and is | ||
| used as a template for translators to build their translations on. |
There was a problem hiding this comment.
| * ``.pot`` files are typically generated by the original author of the cog, and | |
| contain the basic messages in en_US (the language Red is written in), and is | |
| used as a template for translators to build their translations on. | |
| * ``.pot`` files are typically generated by the original author of the cog, and | |
| contain the basic messages in en_US (the language Red is written in). This | |
| file is used as a template for translators to build their translations on. |
Less long winded as two sentences.
| * ``.po`` files (portable objects) are language specific, for example | ||
| ``en-GB.po`` for British English, or ``en-ES.po`` for Spanish. Note that Red | ||
| uses a ``-`` character in the filename, not a ``_`` which is often seen as as | ||
| the standard. |
There was a problem hiding this comment.
Somewhere, possibly here, you should link to https://translate.discord.red/. That site is where translators can contribute to Red's core translations, and lists all of the languages Red supports.
| (with some modifications), which is the standard for providing translations in | ||
| lots of different software projects. | ||
|
|
||
| * ``.pot`` files are typically generated by the original author of the cog, and |
There was a problem hiding this comment.
This section jumps into listing the structure of the files used for translations without any setup. I'm not sure if this needs to be moved, or if it just needs a sentence leading into the content about to be presented.
| the standard. | ||
| * ``locales/`` directory, where ``.po`` files are stored. | ||
|
|
||
| So, if your are the author of a Cog, or you are adding translations for the first |
There was a problem hiding this comment.
This sentence is too unsure to be here. At the highest level, translating is a 3 step process:
- Update the code to reference strings in the proper way that they will be translated, and can be detected as needing translations by
redgettext - Use
redgettextto generate amessages.potfile (must be re-done if strings are changed/added) - Clone the latest
messages.potfile into alang-code.pofile, and fill out themsgstrs for each string with the appropriate translation for that language/string.
At this point in the guide, we only know vaguely what a .pot and .po file are. We should not already be telling the CC they need to generate a .pot file before they have actually updated the code to support translations. We also should not be implying to translators that they can translate a cog simply by generating a .pot file without touching its code.
Realistically there should probably be 3 sections for each of these 3 steps, rather than For cog creators and For translators sections.
| ~~~~~~~~~~~~~~~ | ||
| For Translators | ||
| ~~~~~~~~~~~~~~~ |
There was a problem hiding this comment.
I don't love this header name, but I can't think of a better one. "Writing translations" doesn't seem specific enough, but anything else I think of is too wordy.
| ~~~~~~~~~~~~~~~ | ||
|
|
||
| If your Cog is already made to be translatable by the original Cog author, you | ||
| simply need to write a ``.po`` file for your language. |
There was a problem hiding this comment.
Rather than saying they need to create a .po file for their language, it should probably be explained that either an existing .po file should be edited or the .pot file can be cloned & renamed with the proper language code to be used as a base. If there is no .pot file, the translator will need to ask the CC to add translation support to their cog.
| best to open an issue with the original Cog author to discuss how they would | ||
| like to receive your ``.po`` file language contribution. |
There was a problem hiding this comment.
| best to open an issue with the original Cog author to discuss how they would | |
| like to receive your ``.po`` file language contribution. | |
| best to reach out to the Cog author to discuss how they would prefer to receive | |
| your translation contribution. |
| tools like `poedit | ||
| <https://poedit.net/>`_ to translate the strings in the messages.pot file. There | ||
| are also free online websites that can be used to get you started, like | ||
| https://crowdin.com/ which some developers link to their code repositories, or |
There was a problem hiding this comment.
As mentioned before, Red core (and some third party cogs) do expect users to exclusively use crowdin, rather than PRing in changes directly to .po files. It might make sense to mention that here, or in the next paragraph.
| If your Cog is already made to be translatable by the original Cog author, you | ||
| simply need to write a ``.po`` file for your language. | ||
|
|
||
| You can use a simple text editor to write a ``.po`` file, but you also use popular |
There was a problem hiding this comment.
I would suggest adding a small code block example of what a .po file looks like, and how to edit it. Additionally, there should be a ..warning that anything within curly braces must be left as-is for the code to function correctly, as those are places where a value is inserted into the string.
#: redbot/core/_cog_manager.py:464
msgid "The following paths were removed: {paths}"
msgstr "Les chemins suivants ont été enlevés : {paths}"
There was a problem hiding this comment.
I would suggest just linking to https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html but we actually don't support the majority of that spec yet (the missing features are implemented for redgettext but Red itself lacks support for those constructs) so maybe we will have to wait for that...
|
@Flame442 , thanks for taking the time to review. I've read through your suggestions and comments, and everything generally sounds fine. Because I've not used the project directly, I'm not familiar with some of the style/conventions, thanks for taking the time to point those out. Happy to revise this PR. I'll probably just accept all the suggestions batched up into a single commit, and use another commit where a bit more context is called for / more examples are needed, if that approach is OK for you? Just about to head to bed now, I'll do this when I next get some time available over the next few days. |
|
That sounds fine to me. Let me know when everything is resolved. |
| This is mostly just an implementation detail though and does not affect Cog | ||
| authors or translators. If you are used to gettext, it is important to explain |
There was a problem hiding this comment.
It does affect Cog authors in that our tool can extract command docstrings (which are part of cog's UI) while not extracting all the other docstrings (which generally aren't user-facing). This is what the redgettext usage example listed in this document does and is something that cannot be done with pygettext (which can only do no docstrings or all docstrings). The distinction probably isn't important for translators who just translate whatever .pot file is given to them but is definitely something that Cog authors would want to know.
More so, pygettext will sometime in the future supports more features than pygettext which is actually rather limited - it has no support for plurals or for context-dependent translations. Those features are already implemented in redgettext (see Cog-Creators/redgettext#9, Cog-Creators/redgettext#10, Cog-Creators/redgettext#11) and just haven't been released yet as I was hoping to have a working implementation of relevant runtime features in Red as well to make sure it aligns with what the support was implemented for.
While upstreaming those features to pygettext was mentioned as a possibility (https://discuss.python.org/t/modernize-and-add-missing-features-to-pygettext/26455), a year passed since so it's unclear that there's enough interest to get it there any time soon.
| If your Cog is already made to be translatable by the original Cog author, you | ||
| simply need to write a ``.po`` file for your language. | ||
|
|
||
| You can use a simple text editor to write a ``.po`` file, but you also use popular |
There was a problem hiding this comment.
I would suggest just linking to https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html but we actually don't support the majority of that spec yet (the missing features are implemented for redgettext but Red itself lacks support for those constructs) so maybe we will have to wait for that...
Description of the changes
This is a simple doc PR on the i18n framework page, that hopefully makes translations and internationalization a little more accessible for new Cog authors, and translators.
I confess that I don't actually use the Red project, but simply was helping a friend get started with translations for the first time. I found the docs a bit too brief about how to get started, and think that if there was a bit more explanation about the different types of files, and the ignoring of .mo files, using -'s instead of _'s, and similar, it probably would have been an easier experience.
First time contributor - I've read CONTRIBUTING.md, but my apologies in advance if I've missed a step, as I'm not familiar with this project!
Have the changes in this PR been tested?
Yes (docs only)