unclecatvn/agent-skills / skills/odoo-18.0
odoo-18
VerifiedOdoo 18 development reference for Python models and ORM (search, domain, read_group, compute fields), XML/CSV data and views, OWL/JS client code, QWeb reports, security (ACL, record rules, groups), cron and server actions, migrations and module upgrades, tests, i18n, and performance. Use this skill whenever work involves Odoo 18 or custom addons—even if the user only pastes a traceback, mentions addons/ or __manifest__.py, describes form/list/kanban/XML errors, HTTP controllers, or business rules on models—including building features, fixing bugs, refactoring, or reviewing addon code. Includes CSS/SCSS asset authoring and review for Odoo addons.
references/odoo-18-translation-guide.md
View on GitHub---
name: odoo-18-translation
description: Complete guide for Odoo 18 translations and localization. Covers Python translations with _() and _lt(), JavaScript/OWL translations with _t(), QWeb template translations, field translations with translate=True, PO file structure, translation export/import, language management, and translation term loading.
globs: "**/*.{py,js,xml}"
topics:
- Python translations (_ and _lt)
- JavaScript translations (_t)
- QWeb template translations
- Field translations (translate=True)
- PO file structure
- Translation export/import
when_to_use:
- Adding translatable strings to Python code
- Adding translations to JavaScript/OWL components
- Creating translatable QWeb templates
- Setting up translated fields
- Exporting/importing translations
---
# Odoo 18 Translation & Localization Guide
## Coding Conventions
Translate literal source strings with parameters, never dynamically built strings.
Complete guide for translating and localizing Odoo 18 modules.
## Quick Reference
| Context | Function | Example |
|---------|----------|---------|
| Python code | `_()` | `_("Hello World")` |
| Python module constants | `_lt()` | `TITLE = _lt("Module Title")` |
| JavaScript/OWL | `_t()` | `_t("Hello World")` |
| Field definition | `translate=True` | `name = fields.Char(translate=True)` |
---
## Table of Contents
1. [Python Translations](#python-translations)
2. [Field Translations](#field-translations)
3. [QWeb Template Translations](#qweb-template-translations)
4. [JavaScript/OWL Translations](#javascriptowl-translations)
5. [Module Translation Structure](#module-translation-structure)
6. [Translation Export/Import](#translation-exportimport)
7. [Language Management](#language-management)
8. [Translation Types](#translation-types)
9. [Best Practices](#best-practices)
10. [Anti-Patterns](#anti-patterns)
---
## Python Translations
### Standard Translation Function
**File:** `odoo/tools/translate.py`
```python
from odoo.tools.translate import _
# Simple translation
message = _("Hello World")
# With formatting (positional)
message = _("Hello %s", user.name)
# With formatting (named)
message = _("Hello %(name)s, you have %(count)d messages",
name=user.name, count=5)
```
### Lazy Translation (Module Constants)
For module-level constants that should be translated lazily:
```python
from odoo.tools.translate import LazyTranslate
_lt = LazyTranslate(__name__)
# Module-level constants
MODULE_NAME = _lt("My Module Name")
TITLE_USER = _lt("User")
LABEL_CONFIRM = _lt("Confirm")
# Usage later - translation happens at display time
def get_title(self):
return MODULE_NAME # Translated when displayed
```
**When to use `_lt()`:**
- Module-level constants
- Class-level attributes
- Default values for fields
- Any string defined outside of methods
### Translation with Context
Provide context for translators using comments:
```python
# Button label (verb)
_(_t("Export"))
# File format (noun)
_("CSV")
# For ambiguous terms, add context
_("Delete", context="verb") # To remove something
_("Delete", context="noun") # A deletion record
```
---
## Field Translations
### Simple Field Translation
```python
class MyModel(models.Model):
_name = 'my.model'
_description = 'My Model'
# Entire field value is translated
name = fields.Char(string='Name', translate=True)
description = fields.Text(string='Description', translate=True)
notes = fields.Html(string='Notes', translate=html_translate)
```
**Storage:** Translations stored as JSONB in database:
```json
{
"en_US": "Product",
"fr_FR": "Produit",
"es_ES": "Producto"
}
```
### Field Labels and Help
Field `string` and `help` attributes are automatically translatable:
```python
# These are automatically extracted for translation
status = fields.Selection([
('draft', 'Draft'),
('confirmed', 'Confirmed'),
('done', 'Done'),
], string='Status', help='Document status')
```
### Term-by-Term Translation
For HTML/XML content with translatable terms inside:
```python
from odoo.tools.translate import html_translate
# Each translatable term is translated separately
description = fields.Html(
'Description',
translate=html_translate
)
```
### Accessing Field Translations
```python
# Get translations for a specific field
translations, context = record.get_field_translations('name')
# Returns: [{'lang': 'fr_FR', 'source': 'Name', 'value': 'Nom'}, ...]
# Update field translations
record._update_field_translations('name', {
'fr_FR': 'Nom',
'es_ES': 'Nombre'
})
```
---
## QWeb Template Translations
### Translatable Content
**File:** `odoo/tools/translate.py` (Lines 153-196)
**Translatable Elements:** `span`, `div`, `p`, `h1`-`h6`, `button`, `b`, `i`, `strong`, `em`, `small`, `text`, `option`, etc.
**Translatable Attributes:** `string`, `placeholder`, `title`, `alt`, `help`, `confirm`, `aria-label`, `data-tooltip`, etc.
### Basic QWeb Translation
```xml
<template xml:space="preserve">
<!-- Text content is automatically translatable -->
<div>
<p>This text will be extracted for translation</p>
<h2>Welcome to Odoo</h2>
</div>
<!-- Using JavaScript _t in templates -->
<span t-esc="_t('Translate me')"/>
<!-- String attributes are translatable -->
<button string="Click Me"/>
<field name="name" string="Name" placeholder="Enter name"/>
<!-- Help text -->
<field name="email" help="Email address for notifications"/>
</template>
```
### Disable Translation
```xml
<!-- Disable translation for specific content -->
<span class="fa fa-warning" t-translation="off"> </span>
<!-- Code/technical content -->
<code t-translation="off">user_id</code>
```
### QWeb with Formatting
```xml
<!-- Variables are NOT translated -->
<div>
Hello <t t-esc="user.name"/>,
you have <t t-esc="message_count"/> new messages.
</div>
<!-- For mixed content, split into translatable parts -->
<div>
<t t-esc="_t('Hello %(name)s', name=user.name)"/>
<t t-esc="_t('You have %(count)d messages', count=message_count)"/>
</div>
```
### Translatable Attributes
```xml
<!-- All these attributes are automatically translatable -->
<button string="Save" confirm="Are you sure?"/>
<field name="email" placeholder="email@example.com"/>
<span class="fa fa-info-circle"
title="Information"
data-tooltip="More details"/>
<input aria-label="Search"/>
```
### OWL Component Attributes
```xml
<!-- OWL components with .translate suffix -->
<Component title.translate="Some title"/>
<button label.translate="Click me"/>
```
---
## JavaScript/OWL Translations
### Translation Function
**File:** `addons/web/static/src/core/l10n/translation.js`
```javascript
import { _t } from "@web/core/l10n/translation";
// Simple translation
const message = _t("Good morning");
// With positional argument
const msg = _t("Good morning %s", userName);
// With named arguments
const formatted = _t("Hello %(name)s, you have %(count)d new messages", {
name: user.name,
count: messageCount
});
```
### In OWL Components
```javascript
/** @odoo-module **/
import { Component, useState } from "@owl/swidget";
import { _t } from "@web/core/l10n/translation";
class MyComponent extends Component {
static template = "my_module.MyComponent";
setup() {
this.state = useState({
title: _t("My Component Title"),
message: _t("Loading...")
});
}
showMessage() {
this.displayNotification({
message: _t("Operation completed successfully"),
type: 'success',
});
}
}
```
### Lazy Translations
```javascript
// Translation happens when the value is converted to string
const lazyText = new LazyTranslatedString("Hello", []);
// Later...
console.log(`${lazyText}`); // Translated at this point
```
### Translation with Markup
```javascript
import { markup } from "@odoo/owl";
// HTML-safe markup in translations
const message = _t("I love %s", markup("<b>Odoo</b>"));
// Result: "I love <b>Odoo</b>" (HTML preserved)
```
---
## Module Translation Structure
### Directory Structure
```
my_module/
├── i18n/
│ ├── my_module.pot # Template (source strings)
│ ├── fr.po # French translations
│ ├── de.po # German translations
│ ├── vi.po # Vietnamese translations
│ └── i18n_extra/ # Optional additional translations
│ └── fr_BE.po # Belgian French override
├── models/
│ └── my_model.py # Python with _("text")
├── static/
│ └── src/
│ ├── js/
│ │ └── my_script.js # JS with _t("text")
│ └── xml/
│ └── my_template.xml # QWeb templates
```
### PO File Format
**Example:** `i18n/fr.po`
```po
# Translation of Odoo Server
# This file contains the French translations
msgid ""
msgstr ""
"Project-Id-Version: Odoo Server 18.0\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-01-01 12:00+0000\n"
"PO-Revision-Date: 2024-01-01 12:00+0000\n"
"Last-Translator: \n"
"Language-Team: \n"
"Language: fr_FR\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. module: my_module
#. odoo-python
#: code:addons/my_module/models/my_model.py:45
msgid "Code Lazy, English"
msgstr "Code Lazy, Français"
#. module: my_module
#: model:ir.model.fields,field_description:my_module.field_my_model__name
msgid "Name"
msgstr "Nom"
#. module: my_module
#. odoo-javascript
#: static/src/js/my_script.js:23
msgid "Save"
msgstr "Enregistrer"
#. module: my_module
#: model:ir.model,name:model_my_model
msgid "My Model"
msgstr "Mon Modèle"
```
### Translation Comments
```po
#. odoo-python # Python code translation (_() or _lt())
#. odoo-javascript # JavaScript translation (_t())
# model:ir.model,name:model_my_model
# model:ir.ui.view,view_id:view_my_form
```
### Language Fallback
Odoo automatically falls back through language variants:
```
fr_BE (Belgian French)
↓ (not found)
fr_419 (French generic)
↓ (not found)
fr (French base)
↓ (not found)
en_US (English - default)
```
---
## Translation Export/Import
### Export Translations via UI
1. Go to **Settings** → **Translations** → **Export Terms**
2. Select language
3. Choose format: PO, CSV, or TGZ
4. Select modules to export
5. Download file
### Export Translations via Code
```python
# File: odoo/tools/translate.py
from odoo.tools.translate import trans_export
import io
buffer = io.BytesIO()
trans_export(
lang='fr_FR',
modules=['my_module'],
buffer=buffer,
format='po',
cr=self.env.cr
)
# Save to file
with open('/tmp/my_module-fr.po', 'wb') as f:
f.write(buffer.getvalue())
```
### Import Translations via UI
1. Go to **Settings** → **Translations** → **Import Terms**
2. Select or create language
3. Upload PO file
4. Choose overwrite option
### Import Translations via Code
```python
from odoo.tools.translate import TranslationImporter
translation_importer = TranslationImporter(self.env.cr)
# Load from file
translation_importer.load_file(
filepath='/path/to/i18n/fr.po',
lang='fr_FR'
)
# Or load from file object
with open('/path/to/i18n/fr.po', 'rb') as f:
translation_importer.load(f, fileformat='po', lang='fr_FR')
# Save to database
translation_importer.save(overwrite=True)
```
### Updating Translations
After adding new translatable strings:
```bash
# Update POT file with new strings
./odoo-bin -c odoo.conf -d my_db --i18n-export=my_module/i18n/my_module.pot --addons-path=addons,custom_addons --modules=my_module
```
---
## Language Management
### Language Model
**File:** `odoo/addons/base/models/res_lang.py`
```python
class Lang(models.Model):
_name = 'res.lang'
_description = 'Languages'
name = fields.Char(required=True) # Display name
code = fields.Char(string='Locale Code', required=True) # en_US, fr_FR
iso_code = fields.Char(string='ISO code') # en, fr
url_code = fields.Char(required=True) # en-us, fr-fr
active = fields.Boolean()
direction = fields.Selection([
('ltr', 'Left-to-Right'),
('rtl', 'Right-to-Left')
])
date_format = fields.Char(required=True)
time_format = fields.Char(required=True)
week_start = fields.Selection([
('1', 'Monday'),
('7', 'Sunday')
])
grouping = fields.Char(string='Separator Format')
decimal_point = fields.Char(required=True)
thousands_sep = fields.Char()
```
### Loading a Language
```python
from odoo.addons.base.models.res_lang import Lang
# Activate a language
Lang._activate_lang('vi_VN')
# Or create if not exists
if not Lang.search_count([('code', '=', 'vi_VN')]):
Lang._create_lang('vi_VN')
# Load translation terms for a language
self.env['ir.module.module']._load_module_terms(
modules=['my_module'],
langs=['vi_VN'],
overwrite=False
)
```
### Get Installed Languages
```python
# Get all active languages
languages = self.env['res.lang'].get_installed()
# Returns: [{'code': 'en_US', 'name': 'English'}, ...]
# Get current user language
current_lang = self.env.lang or 'en_US'
```
### Language Context
```python
# Override language for specific operations
records.with_context(lang='fr_FR').name # Returns French value
# In methods
def print_name(self):
lang = self.env.context.get('lang', 'en_US')
print(f"Language: {lang}")
```
---
## Translation Types
### Type: "code"
**Used for:** Python code strings (`_()`, `_lt()`) and JavaScript strings (`_t()`)
**Storage:** Loaded from PO files into memory at runtime
**Location in PO file:**
```po
#. odoo-python
#: code:addons/my_module/models.py:42
msgid "Translate me"
msgstr ""
```
### Type: "model"
**Used for:** Simple field translations (`translate=True`)
**Storage:** JSONB in database column
**Example:**
```python
name = fields.Char(translate=True)
# Stored as: {"en_US": "Name", "fr_FR": "Nom"}
```
### Type: "model_terms"
**Used for:** Term-based field translations (callable translate)
**Storage:** JSONB with individual term translations
**Example:**
```python
description = fields.Html(translate=html_translate)
# Stored as: {"en_US": "<p>Hello</p>", "fr_FR": "<p>Bonjour</p>"}
```
---
## Best Practices
### DO: Use Formatting for Dynamic Content
```python
# GOOD
message = _("Hello %(name)s, welcome to %(app)s", name=user.name, app="Odoo")
```
### DON'T: Concatenate Translated Strings
```python
# BAD - Grammar differs between languages
message = _("Hello") + " " + user.name + ", " + _("welcome")
```
### DO: Translate Complete Phrases
```python
# GOOD - Context preserved
msg = _("Delete selected records?")
```
### DON'T: Split Translatable Phrases
```python
# BAD - Loses context
msg = _("Delete") + " " + _("selected") + " " + _("records")
```
### DO: Provide Context for Ambiguous Terms
```python
# Use comments for translators
# Button label - verb
_(_t("Export"))
# Noun - file format
_("CSV")
```
### DO: Use Lazy Translation for Constants
```python
# GOOD
_lt = LazyTranslate(__name__)
STATUS_DRAFT = _lt("Draft")
STATUS_CONFIRMED = _lt("Confirmed")
```
### DON'T: Use Regular Translation for Constants
```python
# BAD - Translated at definition time (wrong language)
STATUS_DRAFT = _("Draft")
```
---
## Anti-Patterns
### ❌ Dynamic Source Strings
```python
# BAD - Cannot be extracted or translated
message = _(f"User {user.name} created")
# GOOD
message = _("User %(name)s created", name=user.name)
```
### ❌ Translated Technical Terms
```python
# BAD - Technical IDs should not be translated
xml_id = _("my_module.my_record")
# GOOD
xml_id = 'my_module.my_record'
```
### ❌ Conditional Inside Translation
```python
# BAD
if condition:
msg = _("Success")
else:
msg = _("Failure")
# GOOD - Different messages for different cases
msg = _("Operation %(status)s", status='success' if condition else 'failed')
```
### ❌ Translation in Loops
```python
# BAD - Performance issue
for record in records:
name = _(record.name) # Lookup each time
# GOOD - Translate once
label = _("Name")
for record in records:
print(f"{label}: {record.name}")
```
### ❌ HTML in Python Translations
```python
# BAD - HTML should be in QWeb templates
message = _("<strong>Error:</strong> Invalid input")
# GOOD
message = _("Error: Invalid input") # Format in QWeb
```
---
## Translation Testing
### Test Translations in Different Languages
```python
# Switch language context
def test_translations(self):
# Test in French
records_fr = self.records.with_context(lang='fr_FR')
self.assertEqual(records_fr.name, "Nom Français")
# Test in Vietnamese
records_vi = self.records.with_context(lang='vi_VN')
self.assertEqual(records_vi.name, "Tên Tiếng Việt")
```
### Test Translation Loading
```python
def test_translation_loaded(self):
# Ensure translations are loaded
self.env['ir.module.module']._load_module_terms(
modules=['my_module'],
langs=['fr_FR']
)
# Check translation exists
translations = self.env['ir.translation'].search([
('module', '=', 'my_module'),
('lang', '=', 'fr_FR'),
('src', '=', 'Source String')
])
self.assertTrue(translations)
self.assertEqual(translations.value, 'Chaîne traduite')
```
---
## Key Files Reference
| Purpose | File |
|---------|------|
| Core translation system | `odoo/tools/translate.py` |
| Field definitions | `odoo/fields.py` |
| Model translation methods | `odoo/models.py` |
| Language model | `odoo/addons/base/models/res_lang.py` |
| JS translation utilities | `addons/web/static/src/core/l10n/translation.js` |
| Translation web controller | `addons/web/controllers/webclient.py` |
| Export wizard | `odoo/addons/base/wizard/base_export_language.py` |
| Import wizard | `odoo/addons/base/wizard/base_import_language.py` |
| Translation tests | `odoo/addons/base/tests/test_translate.py` |
| Base translation template | `odoo/addons/base/i18n/base.pot` |
---
## Quick Checklist
When adding translatable content:
- [ ] Python strings: Use `_()` for runtime, `_lt()` for constants
- [ ] JavaScript strings: Use `_t()`
- [ ] Field values: Add `translate=True` parameter
- [ ] QWeb templates: Text content is auto-translatable
- [ ] Provide context for ambiguous terms
- [ ] Use formatting for dynamic content
- [ ] Don't concatenate translated strings
- [ ] `i18n/<module>.pot` regenerated after adding/changing strings (`--i18n-export=... --modules=<module>`, see Export/Import)
- [ ] Every shipped locale has a `.po` in `i18n/` refreshed from that `.pot` (`msgmerge --quiet --update --no-fuzzy-matching --backup=none <lang>.po <module>.pot`; Odoo loads `#, fuzzy` entries as real translations)
- [ ] Test in multiple languages
- [ ] Check RTL language support if needed
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |