openspp-modules icon indicating copy to clipboard operation
openspp-modules copied to clipboard
Published 3 weeks ago • verified publisher icon OpenSPP

Document the OpenSPP Translation Workflow

Open jeremi opened this issue 9 months ago • 1 comments

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

Labels

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

Priority

Medium

Size

Small (Completable in a day)

jeremi avatar Mar 02 '25 03:03 jeremi

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

References

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

Sandeep9182-hue avatar Apr 06 '25 17:04 Sandeep9182-hue

There hasn't been any activity on this issue in the past 6 months, so it has been marked as stale and it will be closed automatically if no further activity occurs in the next 30 days. If you want this issue to never become stale, please ask a PSC member to apply the "no stale" label.

github-actions[bot] avatar Oct 05 '25 12:10 github-actions[bot]