From b96442aff9cead05ec64b7aa66c3669a3c8fc254 Mon Sep 17 00:00:00 2001 From: jamesread Date: Thu, 11 Apr 2024 23:23:55 +0100 Subject: [PATCH 1/3] Docs: Improved introduction to i18n for Cog authors and Translators --- docs/framework_i18n.rst | 72 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 8 deletions(-) diff --git a/docs/framework_i18n.rst b/docs/framework_i18n.rst index b305a8e12e3..170764572c6 100644 --- a/docs/framework_i18n.rst +++ b/docs/framework_i18n.rst @@ -7,9 +7,52 @@ Internationalization Framework ============================== ------------ -Basic Usage ------------ +-------- +Tutorial +-------- + +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, +(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 + 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. +* `.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. +* `locales/` directory, where `.po` files are stored. + +So, if your are the author of a Cog, or you are adding translations for the first +time to python code, you would probably generate `.pot` file to make your code +easily translatable. See below for instructions. + +If you are trying to translate part of Red, or a Cog, you would write a `.po` file. + +A technical detail, is that Red actually uses a slightly modified version of +`pygettext`, called `redgettext` (https://github.com/Cog-Creators/redgettext). +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 +that Red does *not use `.mo` files* - it is not necessary to run `msgfmt` or +other tools, it reads the `.po` files directly. + +~~~~~~~~~~~~~~~ +For Cog authors +~~~~~~~~~~~~~~~ + +For authors of Cogs, it's very easy to make your bot translatable using the +Translator class provided - code samples can be found below. In summary, the +steps are; + +* Import the i18n Translator class and cog_i18n decorator. +* Decorate your class with @cog_i18n +* Translate literal strings (eg "This is a test command") to use the underscore + function like _("This a test command") +* Use redgettext to generate a message.pot file +* Write a test `.po` file, and put it in your `locales/` directory relative + to your `.py` code. .. code-block:: python @@ -27,9 +70,7 @@ Basic Usage """command description""" await ctx.send(_("This is a test command")) --------- -Tutorial --------- + After making your cog, generate a :code:`messages.pot` file @@ -42,8 +83,23 @@ This file will contain all strings to be translated, including docstrings. (For advanced usage check :code:`python -m redgettext -h`) -You can now use a tool like `poedit -`_ to translate the strings in your messages.pot file. +~~~~~~~~~~~~~~~ +For Translators +~~~~~~~~~~~~~~~ + +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 +tools like `poedit +`_ 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://www.potranslate.com/upload . + +Once you have written your .po file, you will need to send it back to the Cog +author. Most Cog authors would prefer pull requests on GitHub, but it's probably +best to open an issue with the original Cog author to discuss how they would +like to receive your `.po` file language contribution. ------------- API Reference From c685f9ed0a365bf282a6eae443518de6098847f5 Mon Sep 17 00:00:00 2001 From: jamesread Date: Thu, 11 Apr 2024 23:56:43 +0100 Subject: [PATCH 2/3] Docs: Improved introduction to i18n for Cog authors and Translators (+fixed broken docs test!) --- docs/framework_i18n.rst | 43 +++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/docs/framework_i18n.rst b/docs/framework_i18n.rst index 170764572c6..a5c4968877c 100644 --- a/docs/framework_i18n.rst +++ b/docs/framework_i18n.rst @@ -17,26 +17,28 @@ that use the framework. The framework is based on the popular gettext format, (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 +* ``.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. -* `.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. -* `locales/` directory, where `.po` files are stored. +* ``.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. +* ``locales/`` directory, where ``.po`` files are stored. So, if your are the author of a Cog, or you are adding translations for the first -time to python code, you would probably generate `.pot` file to make your code +time to python code, you would probably generate ``.pot`` file to make your code easily translatable. See below for instructions. -If you are trying to translate part of Red, or a Cog, you would write a `.po` file. +If you are trying to translate part of Red, or a Cog, you would write a ``.po`` +file. A technical detail, is that Red actually uses a slightly modified version of -`pygettext`, called `redgettext` (https://github.com/Cog-Creators/redgettext). +``pygettext``, called ``redgettext`` (https://github.com/Cog-Creators/redgettext). 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 -that Red does *not use `.mo` files* - it is not necessary to run `msgfmt` or -other tools, it reads the `.po` files directly. +that Red does *not use `.mo` files* - it is not necessary to run ``msgfmt`` or +other tools, it reads the ``.po`` files directly. ~~~~~~~~~~~~~~~ For Cog authors @@ -51,8 +53,8 @@ steps are; * Translate literal strings (eg "This is a test command") to use the underscore function like _("This a test command") * Use redgettext to generate a message.pot file -* Write a test `.po` file, and put it in your `locales/` directory relative - to your `.py` code. +* Write a test ``.po`` file, and put it in your ``locales/`` directory relative + to your ``.py`` code. .. code-block:: python @@ -72,10 +74,12 @@ steps are; -After making your cog, generate a :code:`messages.pot` file +After making your Cog, and using the _() function to make your strings +translatable, you will need to generate a :code:`messages.pot` file. We recommend using redgettext - a modified version of pygettext for Red. -You can install redgettext by running :code:`pip install redgettext` in a command prompt. +You can install redgettext by running :code:`pip install redgettext` in a +command prompt. To generate the :code:`messages.pot` file, you will now need to run :code:`python -m redgettext -c [path_to_cog]` @@ -88,18 +92,19 @@ For Translators ~~~~~~~~~~~~~~~ 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. +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 +You can use a simple text editor to write a ``.po`` file, but you also use popular tools like `poedit `_ 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://www.potranslate.com/upload . +https://crowdin.com/ which some developers link to their code repositories, or +https://www.potranslate.com/upload where you can just upload the ``.pot`` file. -Once you have written your .po file, you will need to send it back to the Cog +Once you have written your ``.po`` file, you will need to send it back to the Cog author. Most Cog authors would prefer pull requests on GitHub, but it's probably best to open an issue with the original Cog author to discuss how they would -like to receive your `.po` file language contribution. +like to receive your ``.po`` file language contribution. ------------- API Reference From 10bd4103aa99a39c32f7b0494cd0eb29635990e2 Mon Sep 17 00:00:00 2001 From: James Read Date: Fri, 12 Apr 2024 00:14:56 +0100 Subject: [PATCH 3/3] Apply suggestions aikaterna's from code review Many thanks to @aikaterna for reviewing and suggesting typo fixes. Co-authored-by: aikaterna <20862007+aikaterna@users.noreply.github.com> --- docs/framework_i18n.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/framework_i18n.rst b/docs/framework_i18n.rst index a5c4968877c..5adc6859c6a 100644 --- a/docs/framework_i18n.rst +++ b/docs/framework_i18n.rst @@ -27,7 +27,7 @@ lots of different software projects. * ``locales/`` directory, where ``.po`` files are stored. So, if your are the author of a Cog, or you are adding translations for the first -time to python code, you would probably generate ``.pot`` file to make your code +time to python code, you would probably generate ``.pot`` files to make your code easily translatable. See below for instructions. If you are trying to translate part of Red, or a Cog, you would write a ``.po`` @@ -46,7 +46,7 @@ For Cog authors For authors of Cogs, it's very easy to make your bot translatable using the Translator class provided - code samples can be found below. In summary, the -steps are; +steps are: * Import the i18n Translator class and cog_i18n decorator. * Decorate your class with @cog_i18n