Problem definition:
When carrying out an upgrade of the Odoo system for one of our customers, we noticed that after the process was completed, the data in the translatable fields of the user-defined modules was only available in English. Our subsequent research led to the realization that Odoo had made a change to the translation logic in version 16. It turned out that during the upgrade process, only Odoo's in-house modules were converted to the new logic, while custom modules remained unaffected.
What has changed?
In versions of Odoo prior to version 16, translations were stored at database level in the 'ir_translation' table.
Since the introduction of version 16, however, translatable fields have been saved in the database as a JSONB data type. As the name suggests, the data for all languages is stored in this new system in the form of a JSON object. The 'ir_translation' table is no longer required.
The result is as follows:
Solution: Migration script
After an in-depth discussion with the Odoo support team, it became clear that the only viable solution was to develop custom migration scripts for all custom modules that contain translatable fields.
What are migration scripts?
Migration scripts are a useful tool to transform the data of a custom module so that it is compatible at the database level with the new version of Odoo. The focus here is not on any necessary changes in the code, but rather on necessary adjustments to the data in the database, as is the case with our problem with the translations.
Migration Manager:
Odoo has had integrated migration functionality since TinyERP 4.2. The Migration Manager provides the basic functionality for executing migration scripts and provides a structure in which these can be placed. Below you will find the comment on this class, which describes the basic functions and properties of the Migration Manager in detail:
Manages the migration of modules.
Migrations files must be python files containing a 'migrate(cr, installed_version)'function. These files must respect a directory tree structure: A 'migrations' folder which contains a folder by version. Version can be 'module' version or 'server.module' version (in this case, the files will only be processed by this version of the server). Python file names must start by 'pre-' or 'post-' and will be executed, respectively,
before and after the module initialisation. 'end-' scripts are run after all modules have been updated.
A special folder named '0.0.0' can contain scripts that will be run on any version change.
In 'pre' stage, '0.0.0' scripts are run first, while in 'post' and 'end', they are run last.
Example::<moduledir>
`-- migrations
|-- 1.0
| |-- pre-update_table_x.py
| |-- pre-update_table_y.py
| |-- post-create_plop_records.py
| |-- end-cleanup.py
| `-- README.txt # not processed
|-- 9.0.1.1 # processed only on a 9.0 server
| |-- pre-delete_table_z.py
| `-- post-clean-data.py
|-- 0.0.0
| `-- end-invariants.py # processed on all version update
`-- foo.py # not processed
OpenUpgrade Library:
The OpenUpgrade Library is a project maintained by the Odoo Community Association (OCA) that aims to simplify the process of creating migration scripts. This library provides a variety of utility functions specifically designed to reduce the complexity of migrating custom modules and provide users with a smooth transition.
Odoo Upgrade Util:
Since the end of 2023, Odoo has also provided its own library, Upgrade Util, which is similar in functionality to the OpenUpgrade Library. This library provided by Odoo includes a range of auxiliary functions that are specially designed for the creation and handling of migration scripts. This new development aims to provide users with additional support and resources when performing system upgrades and migrations.
Migration script on a demonstration module:
To better illustrate this process, we have developed a demonstration module for you. This module adds a translatable text field to the 'product.template' model. You can download the module here and see for yourself how it works.
In the Odoo frontend, the whole thing looks like this:
In our example, we use the OpenUpgrade Library because it provides a useful function for migrating translation values. This library can be installed as a Python package using PIP:
pip install openupgradelib
In the demonstration module, you will find the "migrations" folder, which contains a subfolder called "16.0.1.0.0". The file "post-migration.py" is located in this subfolder. As explained in the "Migration Manager" section, this file is executed when the module is updated to version "16.0.1.0.0" after the module is updated.
# -*- coding: utf-8 -*-
from openupgradelib import openupgrade
from openupgradelib.openupgrade_160 import migrate_translations_to_jsonb
@openupgrade.migrate()
def migrate(env, version):
fields_spec = [
('product.template', 'custom_note')
]
migrate_translations_to_jsonb(env, fields_spec=fields_spec)
As you can see, the migration script uses the OpenUpgrade decorator and the "migrate_translations_to_jsonb" function. To be able to use this function, only one parameter in the form of a list of tuples needs to be passed. These tuples should contain the model and field names for which the translation data is to be migrated.
You now have the option of executing your own migration script by updating the relevant module via the command line after you have upgraded Odoo.
python3 <odoo-bin> --config /etc/odoo/odoo.conf -d <upgrade-datenbank> --update=<module> --i18n-overwrite --no-http --stop-after-init
Example:
python3 /opt/odoo/odoo/odoo-bin --config /etc/odoo/odoo.conf -d odoo16-translation-demo --update=manatec_translation_demo --i18n-overwrite --no-http --stop-after-init
Conclusion:
This observation illustrates the need for careful planning and execution of migration scripts when upgrading to Odoo 16 or newer versions, especially when handling translation values in custom modules.
However, thanks to the support provided by the OpenUpgrade Library helper functions, creating these necessary scripts is relatively easy.
Do you have any questions or need support with your upgrade project? Please feel free to contact us at any time! We look forward to your contact request.
Sources: postgresql.org, github.com, oca.github.io