How to Define Translations in a Custom Module & Add a New Language in Odoo 18: Complete Step by Step Guide
By Braincuber Team
Published on April 1, 2026
Odoo is an open-source ERP platform with strong multi-language support. While its default modules support multiple languages simultaneously, custom modules require manual translation configuration. This enables users within the same database to access the system in their preferred language at the same time. When a user changes their preferred language, the interface language, decimal separator, thousand separator, date and time format, first day of the week, and text direction will all be updated based on the settings defined in the language form.
What You'll Learn:
- How to activate a new language in Odoo 18
- How to export translation files in PO format
- How to add translations to the i18n directory
- How to import translation files back into Odoo
- How to add a completely new language using res.lang.csv
Step 1: Activate a New Language in Odoo 18
Before adding translations for a custom module, you must first activate the desired language in your Odoo database. This makes the language available for use across all modules.
Navigate to Language Settings
Go to Settings > Translation > Languages to view all available languages in your Odoo instance.
Verify Permissions
Ensure you have administrator permissions to modify or add new languages. Without proper access rights, you won't be able to activate languages.
Activate the Desired Language
Select the language you want to add from the list and activate it to make it available for use throughout Odoo. This step is required before you can export or import translations for that language.
Settings > Translation > Languages > Select Language > Activate
Step 2: Export Translation Files
Once the language is activated, you can export the translation template for your custom module. This creates a PO file containing all translatable terms from your module.
Open Export Translation Menu
Navigate to Settings > Translations and click the Export Translations menu option.
Configure Export Settings
Fill in the export wizard with the following details:
- Language: Select the target language for translation (e.g., Arabic)
- File Format: Choose PO (recommended for translations). CSV and TGZ archives are also available
- Export Type: Choose whether to export for the entire module or a specific model
- Apps to Export: Select the custom module(s) you want to translate. Multiple modules can be selected
Handle Model-Specific Exports (Optional)
If you selected a specific model in Export Type, two additional fields appear:
- Model to Export: Select the specific model requiring translation
- Model Domain: Apply filters to export only records meeting specific conditions
Download the PO File
Click export to generate the PO file and download it directly to your system.
| Export Field | Description | Example Value |
|---|---|---|
| Language | Target language for translation | Arabic / AR |
| File Format | Format for exported translations | PO (Portable Object) |
| Export Type | Scope of export | Module or Model |
| Apps to Export | Modules to include in export | vehicle_rental |
Step 3: Add Translations to the Module
After downloading the PO file, you need to add it to your custom module's i18n directory and provide the translated strings.
Place PO File in i18n Directory
Add the downloaded PO file to your module's i18n/ directory. The file should be named with the language code, e.g., ar.po for Arabic.
Edit the PO File with Translations
Open the PO file and add the translated msgstr values for each msgid entry. Each msgid contains the original English term, and msgstr is where you provide the translation.
Upgrade the Module
After saving the PO file, upgrade the module from the Apps menu to load the new translations into the database.
msgid "Vehicle Rental"
msgstr "تأجير المركبات"
msgid "Rental Orders"
msgstr "طلبات الإيجار"
msgid "Customer"
msgstr "العميل"
Important: Module Upgrade Required
After adding or modifying PO files in the i18n directory, you must upgrade the module for the translations to take effect. Simply restarting the Odoo server is not sufficient.
Step 4: Verify Translations by Changing User Language
After upgrading the module, change the current user's language preference to verify that translations are working correctly.
Change User Language Preference
Go to Settings > Users & Companies > Users, select your user, and change the Language field to the newly added language (e.g., Arabic).
Verify Translated Terms
Navigate to your custom module and verify that all terms appear in the translated language. The interface direction, date formats, and separators should also update accordingly.
Step 5: Import Translations via Odoo UI
Alternatively, you can import translation files directly through the Odoo interface without modifying module files.
Navigate to Import Translation
Go to Settings > Translations > Import Translation.
Upload Translation File
Upload your edited translation file. You can edit existing terms and upload the updated file.
Enable Overwrite if Needed
To overwrite existing translated terms, enable the overwrite field during import. This replaces any previously imported translations with the new ones.
Step 6: Add a Completely New Language via res.lang.csv
If the language you need doesn't exist in Odoo at all, you can add it programmatically by creating a res.lang.csv file in your custom module's data directory.
Create res.lang.csv File
Create a CSV file named res.lang.csv under your module's data/ directory with the language configuration.
Define Language Properties
The CSV file must include the following columns: id, name, code, iso_code, direction, grouping, decimal_point, thousands_sep, date_format, time_format, week_start.
Update Module Manifest
Add the CSV file to the data list in your module's __manifest__.py and add 'base' to the depends list.
Upgrade Module and Verify
Upgrade the module and verify the new language appears in the language records under Settings > Translation > Languages.
"id","name","code","iso_code","direction","grouping","decimal_point","thousands_sep","date_format","time_format","week_start"
"base.lang_isk","Icelandic / íslenska","is","is","Left-to-Right","[]",",",,"%d-%m-%Y","%H:%M:%S","7"
'depends': ['base'],
'data': [
'security/ir.model.access.csv',
'data/res.lang.csv',
],
Language Properties Reference
The direction field controls text direction (Left-to-Right or Right-to-Left). The week_start field uses numbers 0-6 where 0=Sunday and 6=Saturday. The grouping field defines number grouping patterns for thousands separators.
Key Translation Concepts in Odoo 18
PO File Format
PO (Portable Object) is the recommended format for Odoo translations. It contains msgid/msgstr pairs for each translatable term and supports comments and context.
i18n Directory
The i18n directory in your module stores all translation files. Each language gets its own PO file named with the language code (e.g., ar.po, fr.po, de.po).
Multi-Language Support
Odoo supports multiple languages simultaneously. Each user can have their own language preference, and the interface adapts accordingly without affecting other users.
res.lang Model
The res.lang model stores language configurations including date formats, time formats, decimal separators, and text direction. New languages can be added via CSV data files.
Frequently Asked Questions
How do I export translations for a custom module in Odoo 18?
Go to Settings > Translations > Export Translations. Select the target language, choose PO format, select your custom module, and download the generated file.
Where should I place the PO translation file in my module?
Place the PO file in your module's i18n/ directory with the language code as the filename (e.g., ar.po for Arabic, fr.po for French).
How do I add a language that doesn't exist in Odoo?
Create a res.lang.csv file in your module's data/ directory with language properties, add it to the manifest data list, and upgrade the module.
Do I need to restart Odoo after adding translations?
No, you need to upgrade the module from the Apps menu, not restart the server. Module upgrade reloads the translation files into the database.
Can I overwrite existing translations in Odoo 18?
Yes, when importing translations via Settings > Translations > Import Translation, enable the overwrite option to replace existing translated terms.
Need Help with Odoo Translations?
Our experts can help you configure multi-language support, set up custom module translations, and ensure your Odoo instance serves users in their preferred language.