Document the OpenSPP Translation Workflow

[jeremi]

Document the OpenSPP Translation Workflow

Description

As OpenSPP is used in multiple countries and languages, having clear documentation on the translation workflow is essential. This will help contributors understand how to add or update translations and make OpenSPP more accessible globally. This documentation should be integrated into the existing OpenSPP documentation repository.

Objective

Create a comprehensive guide on OpenSPP's translation workflow that:

1. Explains the PO/POT file system
2. Describes how to add translations for new languages
3. Documents how to update existing translations
4. Outlines best practices for maintaining translations
5. Integrates seamlessly with the existing OpenSPP documentation structure

Tasks

• Review current documentation in the OpenSPP documentation repository for any existing translation-related content
• Document the structure of translation files in OpenSPP
• Explain how to extract translatable strings
• Provide step-by-step guides for adding a new language
• Document the process for updating existing translations
• Outline how translations are loaded and used in the system
• Include examples and screenshots
• List useful tools for working with PO/POT files
• Format and structure the documentation to match the existing OpenSPP documentation style
• Submit the documentation to the OpenSPP documentation repository following contribution guidelines

Expected Outputs

• Markdown documentation of the translation workflow ready for integration with the OpenSPP documentation repository
• Example-based tutorial for adding a new language
• Explanation of PO/POT file structure with examples
• Best practices section
• Pull request to the OpenSPP documentation repository

Good First Tasks for the Sprint

• Review existing documentation structure in the OpenSPP documentation repository
• Map the current translation file structure
• Document the process for extracting strings
• Create a simple example of adding translations for one module
• List and explain translation-related commands

Resources

• Odoo Translation Documentation
• Python polib Documentation
• OpenSPP Documentation Repository
• OpenSPP Documentation Website

Labels

documentation, good-first-issue, beginner-friendly, enhancement, size:S

Priority

Medium

Size

Small (Completable in a day)

[Sandeep9182-hue]

OpenSPP Translation Workflow Guide

This guide explains how to contribute to the translation workflow in OpenSPP, helping make the platform accessible in multiple languages.

---

Objective

This guide will help you:

• Understand how OpenSPP handles translations (PO/POT file system)

• Add new language translations

• Update existing ones

• Follow best practices for maintaining clean and accurate localization

---

Understanding Translation Files

OpenSPP uses .po (Portable Object) and .pot (Portable Object Template) files based on the Odoo framework.

• .pot: Template file containing translatable strings (English source)

• .po: Language-specific translation file (e.g., fr.po for French)

Location example:

addons/your_module/i18n/fr.po

---

Step-by-Step: Add a New Language Translation

1. Navigate to the Module Directory

cd openspp/openspp-modules/your_module/

2. Generate a .pot Template File

python3 ../../odoo-bin --addons-path=addons,your_module_path -d your_db_name --i18n-export=your_module/i18n/your_module.pot --modules=your_module --language=en_US --stop-after-init

3. Create a .po File from the .pot Template

You can use tools like msginit or copy the .pot manually:

cp i18n/your_module.pot i18n/fr.po

Edit the header and add translations:

msgid "Invoice"
msgstr "Facture"

4. Install the Language in OpenSPP UI

• Go to Settings → Translations → Languages → Load a Translation

• Choose your language and install it

5. Load Translations

python3 ../../odoo-bin -d your_db_name -u your_module --load-language=fr_FR

---

Step-by-Step: Update Existing Translations

1. Export Updated .pot

python3 ../../odoo-bin --addons-path=addons,your_module_path -d your_db_name --i18n-export=i18n/your_module.pot --modules=your_module --language=en_US --stop-after-init

2. Merge .pot with Existing .po

msgmerge --update i18n/fr.po i18n/your_module.pot

3. Edit and Translate New Entries

Open the file using a PO editor or text editor and fill in untranslated msgstr entries.

---

Translation File Structure Example

msgid "Name"
msgstr "Nom"
msgid "Invoice Amount"

msgstr "Montant de la facture"

---

🔧 Tools for Managing Translations

Tool	Description
msgmerge	Merges .pot into .po file
msginit	Initializes a new .po file
Poedit	GUI-based PO file editor
polib	Python library to parse .po and .pot files
Transifex	Web-based translation platform (optional use)

---

Best Practices for Translation Contributors

• Always pull the latest code and .pot files before working

• Use clear, culturally appropriate, and grammatically correct translations

• Keep formatting tokens (%s, %(name)s) intact

• Avoid translating technical terms unless localized appropriately

• Test translations in the UI after applying

---

Suggested Screenshots

• Adding language from UI

• PO file opened in a GUI editor (e.g., Poedit)

• Translation loaded in OpenSPP interface

---

Example Use Case

You want to translate the openspp_finance module into Spanish:

1. Navigate to openspp-modules/openspp_finance

2. Export .pot using --i18n-export

3. Copy .pot to es.po

4. Add Spanish translations

5. Load Spanish language via OpenSPP UI

6. Apply using --load-language=es_ES

---

Submitting Your Translation

• Commit your .po files to the module's i18n directory

• Follow contribution guidelines from the OpenSPP Documentation Repository

• Submit a Pull Request

---

References

• Odoo Translation Docs

• Python polib

• OpenSPP Documentation

This guide aligns with OpenSPP’s documentation format and should be included under a new section such as translations.md.

# OpenSPP Translation Workflow Guide

This guide explains how to contribute to the translation workflow in OpenSPP, helping make the platform accessible in multiple languages.

---

Objective

This guide will help you:

• Understand how OpenSPP handles translations (PO/POT file system)
• Add new language translations
• Update existing ones
• Follow best practices for maintaining clean and accurate localization

---

Understanding Translation Files

OpenSPP uses .po (Portable Object) and .pot (Portable Object Template) files based on the Odoo framework.

• .pot: Template file containing translatable strings (English source)
• .po: Language-specific translation file (e.g., fr.po for French)

Location example:

addons/your_module/i18n/fr.po

---

Step-by-Step: Add a New Language Translation

1. Navigate to the Module Directory

cd openspp/openspp-modules/your_module/

2. Generate a .pot Template File

python3 ../../odoo-bin --addons-path=addons,your_module_path -d your_db_name --i18n-export=your_module/i18n/your_module.pot --modules=your_module --language=en_US --stop-after-init

3. Create a .po File from the .pot Template

You can use tools like msginit or copy the .pot manually:

cp i18n/your_module.pot i18n/fr.po

Edit the header and add translations:

msgid "Invoice"
msgstr "Facture"

4. Install the Language in OpenSPP UI

• Go to Settings → Translations → Languages → Load a Translation
• Choose your language and install it

5. Load Translations

python3 ../../odoo-bin -d your_db_name -u your_module --load-language=fr_FR

---

Step-by-Step: Update Existing Translations

1. Export Updated .pot

python3 ../../odoo-bin --addons-path=addons,your_module_path -d your_db_name --i18n-export=i18n/your_module.pot --modules=your_module --language=en_US --stop-after-init

2. Merge .pot with Existing .po

msgmerge --update i18n/fr.po i18n/your_module.pot

3. Edit and Translate New Entries

Open the file using a PO editor or text editor and fill in untranslated msgstr entries.

---

Translation File Structure Example

msgid "Name"
msgstr "Nom"

msgid "Invoice Amount"
msgstr "Montant de la facture"

---

🔧 Tools for Managing Translations

Tool	Description
msgmerge	Merges .pot into .po file
msginit	Initializes a new .po file
[Poedit](https://poedit.net/)	GUI-based PO file editor
[polib](https://polib.readthedocs.io/)	Python library to parse .po and .pot files
[Transifex](https://www.transifex.com/)	Web-based translation platform (optional use)

---

Best Practices for Translation Contributors

• Always pull the latest code and .pot files before working
• Use clear, culturally appropriate, and grammatically correct translations
• Keep formatting tokens (%s, %(name)s) intact
• Avoid translating technical terms unless localized appropriately
• Test translations in the UI after applying

---

Suggested Screenshots

• Adding language from UI
• PO file opened in a GUI editor (e.g., Poedit)
• Translation loaded in OpenSPP interface

---

Example Use Case

You want to translate the openspp_finance module into Spanish:

1. Navigate to openspp-modules/openspp_finance
2. Export .pot using --i18n-export
3. Copy .pot to es.po
4. Add Spanish translations
5. Load Spanish language via OpenSPP UI
6. Apply using --load-language=es_ES

---

Submitting Your Translation

• Commit your .po files to the module's i18n directory
• Follow contribution guidelines from the [OpenSPP Documentation Repository](https://github.com/openspp/documentation)
• Submit a Pull Request

---

References

• [Odoo Translation Docs](https://www.odoo.com/documentation/16.0/developer/reference/i18n.html)
• [Python polib](https://polib.readthedocs.io/en/latest/)
• [OpenSPP Documentation](https://github.com/openspp/documentation)

Creating example .po and .pot files?

Folder Structure Example
markdown
Copy
Edit
openspp-modules/
└── openspp_example/
├── init.py
├── manifest.py
├── models/
│ └── example_model.py
└── i18n/
├── openspp_example.pot
└── fr.po

1. .pot File (Template for Translations)
   openspp_example/i18n/openspp_example.pot

po
Copy
Edit

Translation template for OpenSPP Example module

msgid ""
msgstr ""
"Project-Id-Version: OpenSPP Example Module\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2025-04-06\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. module: openspp_example
#: model:ir.ui.menu,name:openspp_example.menu_main
msgid "Example Menu"
msgstr ""

#. module: openspp_example
#: model:ir.model.fields,field_description:openspp_example.field_example_name
msgid "Name"
msgstr ""
2. .po File (French Translation)
openspp_example/i18n/fr.po

po
Copy
Edit

French translation for OpenSPP Example module

msgid ""
msgstr ""
"Project-Id-Version: OpenSPP Example Module\n"
"Language: fr\n"
"POT-Creation-Date: 2025-04-06\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. module: openspp_example
#: model:ir.ui.menu,name:openspp_example.menu_main
msgid "Example Menu"
msgstr "Menu Exemple"

#. module: openspp_example
#: model:ir.model.fields,field_description:openspp_example.field_example_name
msgid "Name"
msgstr "Nom"
Tips
Place both .pot and .po inside the module’s i18n/ directory.

After editing .po, load it using:

bash
Copy
Edit
python3 odoo-bin -d your_db -u openspp_example --load-language=fr_FR
You can create .po for any language (es.po, de.po, hi.po, etc.).