Fix #889. Write docs for how to do translations.

Moult · Moult · commit d5aff85b3503 · 2024-04-17T14:42:54.000+02:00
diff --git a/.gitignore b/.gitignore
@@ -76,6 +76,9 @@ src/ifcopenshell-python/test/build
 # blenderbim libs
 src/blenderbim/blenderbim/libs
 
+# blenderbim i18n
+src/blenderbim/blenderbim/translations.py
+
 # blenderbim test temp files
 src/blenderbim/test/files/temp
 src/blenderbim/drawings
diff --git a/src/blenderbim/blenderbim/translations.py b/src/blenderbim/blenderbim/translations.py
@@ -0,0 +1,3 @@
+# This file will be autogenerated and rewritten when packaged.
+
+translations_dict = {}
diff --git a/src/blenderbim/docs/devs/images/translation-panel.png b/src/blenderbim/docs/devs/images/translation-panel.png
diff --git a/src/blenderbim/docs/devs/translations.rst b/src/blenderbim/docs/devs/translations.rst
@@ -0,0 +1,76 @@
+Translations
+============
+
+The BlenderBIM Add-on supports translations to all languages that Blender
+supports. We'll describe how you can help translate the add-on as a translator,
+or how you can ensure your strings are translatable as a developer.
+Translations are managed using a separate add-on built for this purpose.
+
+1. Clone the `blenderbim-translations
+   <https://github.com/IfcOpenShell/blenderbim-translations>`_ repository. This
+   repository holds all the core translation strings in ``.po`` format.
+2. Download the `blenderbim-translations add-on
+   <https://github.com/IfcOpenShell/IfcOpenShell/blob/v0.7.0/src/blenderbim/scripts/bbim_translations.py>`_
+   and install it as a Blender add-on. This add-on lets you convert translation
+   data to and from the ``.po`` files to the BlenderBIM Add-on.
+3. In the **Render Properties** tab, find the **BlenderBIM Translations**
+   panel, and browse to where you have closed the ``blenderbim-translations``
+   repository, and click on **Setup Translation UI**.
+
+You should now see a new interface with two buttons.
+
+.. image:: images/translation-panel.png
+
+How to translate the add-on
+---------------------------
+
+Before beginning, look inside the ``blenderbim-translations`` repository for a
+``.po`` file for the language you want to translate to (e.g. ``de_DE.po`` for
+German). If this file does not yet exist, congratulations! You are the first
+person to translate to this language! Create a folder in
+``blenderbim-translations`` with your language code and copy the
+``blenderbim.pot`` language template file to that folder and rename it
+according to your language (e.g. for German you would copy ``blenderbim.pot`` to
+``de_DE/de_DE.po``).
+
+Supported language codes are:
+
+.. code-block::
+
+    'ca_AD', 'en_US', 'es', 'fr_FR', 'ja_JP', 'sk_SK', 'cs_CZ', 'de_DE',
+    'it_IT', 'ka', 'ko_KR', 'pt_BR', 'pt_PT', 'ru_RU', 'uk_UA', 'vi_VN',
+    'zh_HANS', 'zh_HANT', 'ab', 'ar_EG', 'bg_BG', 'el_GR', 'eo', 'eu_EU',
+    'fa_IR', 'fi_FI', 'ha', 'he_IL', 'hi_IN', 'hr_HR', 'hu_HU', 'id_ID',
+    'ky_KG', 'ne_NP', 'nl_NL', 'pl_PL', 'sr_RS', 'sr_RS@latin', 'sv_SE', 'sw',
+    'ta', 'th_TH', 'tr_TR'.
+
+As a translator, it is recommended to translate text in bulk by modifying the
+``.po`` files directly. We recommend installing software such as `Poedit
+<https://poedit.net/>`_. These translation software offer features such as auto
+translation, suggestions, and tracking. Alternatively, you may edit the ``.po``
+file as a text file.
+
+Once you have edited the relevant language's ``.po`` file, click on the
+**Update Translations From .po** button in the **BlenderBIM Translations**
+panel.
+
+How to add new translation strings
+----------------------------------
+
+When you have new strings to translate, press the **Parse BlenderBIM strings to
+.pot** button. This detects strings in the source code using regex patterns and
+writes out to the ``blenderbim.pot`` language template file. You may then diff
+this file and propagate changes manually to all translated ``.po`` files.
+
+The ``.pot`` file is only used as a blank template for users to create or
+compare ``.po`` files. The ``.po`` files are the source of truth for
+translation strings. Blender does not read from the ``.pot`` or ``.po`` files.
+Instead, Blender reads from ``blenderbim/translations.py`` which contains a
+dictionary of strings formatted specifically for Blender. The
+``translations.py`` file is generated from the ``.po`` files. This is generated
+when we distribute installable packages, or when translators manually press the
+**Update Translations From .po** button.
+
+.. warning::
+
+   Do not commit the ``translations.py`` file as it is auto-generated.
diff --git a/src/blenderbim/docs/index.rst b/src/blenderbim/docs/index.rst
@@ -42,6 +42,7 @@ Learn how to model a small building and create simple architectural plans, secti
    devs/hello_world
    devs/running_tests
    devs/writing_docs
+   devs/translations
    devs/undo_system
    devs/system_support
    devs/ux_guidelines

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# This file will be autogenerated and rewritten when packaged.`
	`2`	`+`
	`3`	`+translations_dict = {}`