Projects:Translation Management/Functional Specifications
Translation Management - Functional Specifications
Overview
Purpose
The purpose of this project is to examine the processes and tools used to provide the translation of the Openbravo ERP application from the English Base Language into other languages as desired by the final user.
This document will cover the key areas of:
- Generating a translation from the base English installation (or other translation packs)
- Monitoring and rating existing translations and updates within a localization repository
- Installation of a translation within Openbravo ERP
- Refining a translation within Openbravo ERP
- Testing and migrating translations within a development life cycle
- Translation of business data, e.g. product names
- Translation of external documents, e.g. purchase orders
Current analysis of competitors shows that in other products it is far simpler to enable a new language pack in those applications than it is within the Openbravo ERP framework. The target for enabling an existing language should be 8 mouse clicks from logging into the system.
Scope
This project is to cover the process of translating Openbravo ERP and the processes involved in implementing translations into a functioning application. This will not cover topics related to internationalization such as date formatting, accounting requirements, etc.
Some discussion has taken place regarding the possibility of creating translations for business data (Installation specific enterprise data) in order to show the likes of product information translated for viewing purposes. Implementation of a possible solution for this will be dependent on time frames and priorities. This may be included as a separate phase of this project.
The functionality contained in this document is intended to be delivered for version 2.50.
References
Design Considerations
The architecture of the final implementation will fit with the current framework for Openbravo ERP including the use of the XMLEngine, WAD, Application Dictionary, and MDD.
Assumptions
All development will take place using current standards within Openbravo ERP, this will govern the creation of user interface elements, performance targets, and syntax and naming conventions.
Dependencies
There are no dependencies on other projects outside of what is contained in this document.
Constraints
The creation of new forms/windows within the Application Dictionary framework will always involve the compilation of the window. In this instance it will not be possible to create and deploy a translation for this window without the need to compile the application.
Glossary
- Base Language: by default the base language in Openbravo is en_US
- CLDR: Common Locale Data Repository
- CLIR: Cross Language Information Retrieval
- Entity: client as specified in Openbravo ERP
- External Document: a report, document produced by the application that may be printed or email separately from the application, e.g. Trial Balance, Sales Invoice
- I18n: Internationalisation
- ISO: International Standards Organisation
- l10n: Localisation
- Language ISO Code: format is ll_CC. 2 character language code (ll) and 2 character country code (CC).
- Language Pack: collection of files containing translated text
- LDML: Locale Data Markup Language
- LISA: Localization Industry Standards Association
- Locale: formatting rules relating to a location
- Migration: moving from a development installation to a live installation
- MLS: Multiple Language Support - the provision of translated business data enabling content, not just structure, of the application to be translated.
- NLS: Native Language Support
- OSCAR: Open Standards for Container/Content Allowing Reuse
- PO: Portable Object
- Repository: central store of Openbravo translations
- System Language: A system language is a translation pack for the structure of the application. System Language content reflects the content of the Base Language translated into another language/country instance.
- TMX: Translation Memory eXchange
- Translation: a language, country, version combination containing status information and a language pack
- Translation File: a file comtaining translated application text
- XLIFF: XML Localisation Interchange File Format
Functional Requirements
User roles & profiles
- System Admin: Installs translations in the application.
- Translator: Updates translations that can then be used in the application.
- Developer: Creates windows and customisations that use a translation framework to enable a language specific version of the customisation.
- User: Works with the functionality in the application and specifies the language they would like to view the user interface in. Chooses a language from those that are active within the application.
Workflow Diagrams
Login to Language Window
Install a new language pack
Retrieve language details
Copy from language
Install language pack
Export a language pack
Business process definition
BPTRL1. Installing a new language pack
This process involves a System Admin user making an existing language pack available within the application for users. The process should be smooth and clean and take place completely within the application user interface. Installing the language pack should not require the user to recompile the application to make the translated windows/tabs/forms etc available within the application. This business process has a relationship with BPTRL4 in that language packs should be retrieved from the repository. This process will be extended by BPTRL2 to enable the Translation user to load translations from a local directory also.
BPTRL2. Creating a new language pack
Where a language pack is not available for a relevant language/country combination then a user should be able to extract the relevant text strings from the application in a format that allows to translate them with a specified translation tool. This translation should be able to be imported into the application through the user interface where it can be enabled by BPTRL1. A translator should have the ability to generate a new translation pack from scratch or by copying an existing language pack and editing it.
BPTRL3. Updating translations within the application
BPTRL3A. RealTime translation updates
The user will have the ability to update the language pack translations from within the user interface of the application. This will only be available for users operating the application within a specific Translator role.
BPTRL3B. Sharing updated translations with the community
For updates to existing language packs and new language packs created by the translator there will be a function which will allow them to share the updates/creation with the community. This sharing will be through a language pack repository (BPTRL4).
BPTRL4. Repository of language packs
Openbravo ERP will provide a repository/portal for the community to share and obtain language packs for the relevant version of Openbravo ERP. This repository will allow language packs to be marked with a quality rating to show the suitability for live deployment in line with releases of the Openbravo ERP application (Alpha, Beta, Stable).
BPTRL5. Migration of language packs
A mechanism or workflow will be provided by Openbravo ERP which will allow users to apply translations to their installations in line with good development life cycle practices. This will entail first testing the language pack and then migrating the accepted pack to the live application. This process will allow updates to be retrieved or created language packs and the overriding of default translations.
BPTRL6. Multiple Language Support
The application should provide the mechanism whereby a user of the application can generate information and documentation in a target customer language.
e.g. A customer located in Poland and the supplier located in Portugal. The client is located in Spain. The client should be able to use the application in their native Spanish but also be able to produce a purchase order in Portuguese and a sales invoice in Polish. This will be possible even though Portuguese and Polish are not available as System Languages.
Multiple Language Support (MLS) is the extension of a System Language enabling an implementation to translate 'Business Data' into another language. This other language may or may not be defined as a System Language within the application. Multiple Language Support differs from a standard System Language in that it focuses on the content of client populated data, e.g. products, payment terms.
By definition Multiple Language Support is the content of fields, not the label or field.
Example:
- In the Product Window there is a field Name which is a System Language element and thereby allows you to translate the label.
- The content of the Name field is a Multiple Language Support element and as such allows you to translate the value of the content.
By default System Language fields should be defined by Openbravo ERP and will generally start with the AD_ prefix. Multiple Language Support elements will be defined by the applications System Administrator with responsibility for the installed instance. By default there will be certain business data elements defined as enabled for Multiple Language Support, these settings can be overridden by the system administrator to enable or disable as required.
Multiple Language Support elements will not be available through the central repository as it is considered to be installation specific information and generally not applicable to a shared context in regards to the Openbravo Community. As always there are exceptions to the rule and certain tables will be specified as part of the System Language and hence incorporated into the community translations.
For Multiple Language Support defined tables and windows a user of the system will be able to enter data into the application in their defined language. The application will provide background functionality that will ensure the data is persisted in the application in a correct manner.
BPTRL7. Language Pack Installation at Install
During the process of installing the Openbravo ERP application the installer should offer the option to retrieve and install languages other than the default base language. At this point it should also be possible to select a language pack from a local location as well as the central repository.
Use Cases
User stories
The following table shows a break down of the user stories identified to complete the functional specification within this document.
| ref | title | func spec ref | Business Proc ref | description | estimation | priority | dependencies | issue |
|---|---|---|---|---|---|---|---|---|
| 1 | Language Creation/Definition | TRL1 | BPTRL1 | The system should allow the user to define a new language within the application easily and quickly | - | HIGH | - | - |
| 2 | Source existing translations | TRL2 | BPTRL1 | The system should allow the user to locate an existing translation quickly and easily from within the application itself. This ability will be dependent on the users rights | - | HIGH | 8 | 3993 |
| 3 | Create a New Translation | TRL3 | BPTRL2 | The system should provide the user with a simple and efficient means to create a new language pack | - | MEDIUM | 12,13,14 | - |
| 4 | Importing a New System Language | TRL4 | BPTRL1 | The system should provide the user with a mechanism to import a language pack into the application. This should be achieved without the user needing to go outside the application | - | HIGH | 2 | 3394, 3993 |
| 5 | Enable a New System Language | TRL5 | BPTRL1 | The system should allow a qualified user to enable a new translation for users without having to recompile and deploy the application | - | HIGH | 1 | - |
| 6 | Refine an Implemented System Language | TRL6.1 | BPTRL3 | The system will enable a qualified user to amend translations within the application interface | - | MEDIUM | - | - |
| 7 | Retrieve Updates to Language Packs | TRL6.2 | BPTRL3 | The system should provide a mechanism that allows a qualified user to retrieve updated translations provided by other implementers/translators | - | LOW | 8 | - |
| 8 | Translation Repository | OTRL1 | BPTRL4 | The system will provide a central repository that allows Openbravo ERP implementers access to submit and retrieve translation packs and updates | - | HIGH | - | - |
| 9 | Accept Translation Updates | RTRL1 | BPTRL3/ BPTRL4 | The system will allow implementers of Openbravo ERP to submit updated translations to the central repository from within the application | - | LOW | 8 | - |
| 10 | Score/Quality Rate Translations | RTRL2 | BPTRL4 | The system will provide a mechanism that allows the community and Openbravo ERP to rate a translation (new or update) for quality and suitability for implementation | - | LOW | - | - |
| 11 | Publish New/Updated Translations | RTRL3 | BPTRL4 | The system will provide a mechanism to enable translations (new and updates) to implementers of Openbravo ERP. This mechanism will include the quality/score for the translation to allow the implementer to decide if they wish to implement the translation into a live installation | - | LOW | 8 | - |
| 12 | Copy the Base Language | NTRL1 | BPTRL2 | The system will provide translators with the ability to copy the system base language for translation | - | MEDIUM | - | - |
| 13 | Export a Language Pack | NTRL2 | BPTRL2/ BPTRL3 | The system will allow translators to export all relevant fields and strings to a file type that allows them to parse the values for translation | - | MEDIUM | 1 | 3230, 3993 |
| 14 | Translating Files | NTRL3 | BPTRL1 | The system will provide a default mechanism for translation of application strings and generation in a format that allows the translation to be installed into an Openbravo ERP implementation | - | HIGH | - | 3394 |
| 15 | Submit New Translations to Repository | NTRL4 | BPTRL2/ BPTRL3/ BPTRL4 | The system will provide a convenient method for a new Translation to be submitted to a central repository for distribution to the community and implementers | - | LOW | 8 | - |
| 16 | Translator User Role | TRL7 | BPTRL1 | The system will allow rights to be assigned to a user with specific translation functionality. This role will have rights to update language packs within the application interface | - | LOW | - | - |
| 17 | Define elements for Multiple Language Support | MLS1 | BPTRL6 | The application will provide System Admin users with the ability to define elements of the business data for MLS | - | MEDIUM | - | 3262, 3452 |
| 18 | Export MLS Business Data | MLS2 | BPTRL6 | The system will allow a Translator to export all 'Business Data' elements within the application marked for MLS to external files in a format that allows the translator to create translations for these files | - | LOW | 13,17 | 3262, 3452 |
| 19 | External Document Translation | EXTRL1 | BPTRL6 | The system will allow translation of external documents into languages other than those defined as available in the user interface. A user should be able to create a document in the language of a customer other than those defined as system languages | - | MEDIUM | 17 | 3333, 2377, 2202 |
| 20 | Install languages during installation | INSTRL1 | BPTRL7 | The system will allow the installation of other languages during the installation process | - | LOW | 2,4 | 3322 |
| 21 | Install multiple languages during installation process | INSTRL2 | BPTRL7 | The system will allow the installation of multiple languages during the initial installation process of Openbravo ERP | - | LOW | 20 | 3322 |
| 22 | Default user language selection | TRL8 | BPTRL1 | The system will make it possible to configure a default user language per user. If this default language does not exist, the users operating systems language should be selected. Users may want to have their operating system on a language but access to Openbravo ERP using another language | - | LOW | 1 | 3235 |
| 23 | Delete translation texts with their parent original text | TRL9 | BPTRL3 | The system will allow an authorised user to delete an element from the application and by doing so will also delete the translations for that text also. The translation text should not stop a valid deletion process | - | LOW | - | 3331 |
| 24 | Enable MLS data input in native language | MLS1 | BPTRL6 | The application will enable a user to enter data into a window in their native language and the application will ensure that the data is persisted in the application in both the default table and the translated language table. | - | MEDIUM | - | 2202 |
Functional requirements based on business processes
BPTRL1. Installing a New Language Pack
TRL1. Language creation/definition
User Story
The system should allow the user to define a new language within the application easily and quickly
Functional Requirements
The process of installing a new language in the application will start with the definition of a new language. The System Admin user selects the language from the drop down selector (these values are user readable names for the standard ISO Language/Country pairings and should be available from a prepopulated list). Should the translator wish to they can create a new version of this language/country combination, although this option is not mandatory. The user will then click save to store this information in the application.
| Tab | Label | Type | Required | Read Only | Default Value |
|---|---|---|---|---|---|
| Language | Entity | Combo Selector | True | False | System |
| Language | Organisation | Combo Selector | True | False | * |
| Language | Name | Combo Selector | True | False | |
| Language | ISO Code | Text Box | False | Read Only | |
| Language | Activated | Tick Box | False | False | False |
| Language | Status | Text Box | False | True | |
| Language | Statistics | Multiline Text | False | True | |
| Language | Translated By | Multiline Text | False | False |
TRL2. Source existing translations
User Story
The system should allow the user to locate an existing translation quickly and easily from within the application itself. This ability will dependent on the users rights.
Functional Requirement
When the System Admin user selects a new language/country combination the system will make a call to the Openbravo ERP language repository and retrieve the appropriate language pack header information. This process will be an automated background process and will generate and locate the language pack within the appropriate location/country within Openbravo ERP's file structure.
Should a direct matching language pack not be available the user will be shown a list of options from the criteria selected. This criteria will show all language packs that match with either the language, the country, or the default language pack en_US. From this listing the user will have the option to select the one they wish to use.
TRL4. Importing a New System Language
User Story
The system should provide the user with a mechanism to import a language pack into the application. This should be achieved without the user needing to go outside the application.
Functional Requirement
Once the System Admin user has selected a language pack to use and completed the remaining mandatory fields the user will click the save icon in the toolbar. At this point the application will retrieve the language pack from the repository and extract this information into the current application.
This installation process will involve writing the information to the application database and copying the files to a defined application folder. The important step here is writing the data to the database to provide persistence in the translated user interface in the event of a server deployment failure.
TRL5. Enable a New System Language
User Story
The system should allow a qualified user to enable a new translation for users without having to recompile and deploy the application.
Functional Requirement
Within the language screen the user will select the language/country/version combination they wish to enable. Either through creating the language (TRL1) and selecting the activated field or locating an already saved combination and selecting the same field.
Once the activated field is selected the language pack will be available for selection by application users.
TODO: need to link this to the status of a translation.
NTRL3. Translating Files
User Story
The system will provide a default mechanism for translation of application strings and generation in a format that allows the translation to be installed into an Openbravo ERP implementation.
Functional Requirement
In order to remove the need to compile the application to install a translation within the application a new mechanism is required to link the fields in the user interface with the language the user has requested.
To address this a process will be added during the XMLEngine generation process which will link the tags in the fields to the translation. Further information relating to this will be provided in the technical documentation.
TRL7. Translator User Role
User Story
The system will allow rights to be assigned to a user with specific translation functionality. This role will have rights to update language packs within the application interface.
Functional Requirement
As part of the base implementation of an Openbravo ERP installation a default role will be created for Translator users. This role will have access to the Language window and related functionality, including real time updates (within the user interface), importing/exporting system languages, and updating/sharing language updates between the application and the repository.
The Translator user will be separated from the System Admin role in that this user will not have total access to the Application Dictionary.
TRL8. Default user language selection
User Story
The system will make it possible to configure a default user language per user. If this default language does not exist, the users operating systems language should be selected. Users may want to have their operating system on a language but access to Openbravo ERP using another language.
Functional Requirement
This comes from this feature request (3235). When Openbravo ERP is installed it comes with the base language en_US. The System Admin will then install other languages as applicable for the Client. However when a new user is created the default language for each new user will be the base language. This user story is to be able to define another language as the default language when creating users. This will only happen when the user has not set a default language in the Role Selector window.
e.g. Application installed in an Italian speaking company. Base language will be the default language for all users. System Admin installs Italian language pack in the application as users will be working with the application in Italian - English will still be the default language when a user is created and logs into the application. The users then login to the application, change the language in the Role Selector window, and then ticks the Default check box.
To fix this the System Admin should be able to set Italian as the De facto base language and therefore the default for all new users.
BPTRL2. Creating a new Language Pack
TRL3. Create a New Translation
User Story
The system should provide the user with a simple and efficient means to create a new language pack.
Functional Requirement
Creation of a new language pack should always be done in a development installation of the Openbravo ERP application.
To create a new language pack the user will follow the process for defining and installing a new language pack. However in this case the language/country combination selected will be the one that best suits the starting point for the new translation (NTRL1). In this way the translator can select to use the base English/USA language and translate everything or start with a matching translation for the same language but which relates to a different country. This step will allow the translator to start with a partially completed translation.
NTRL1. Copy the Base Language
User Story
The system will provide translators with the ability to copy a language definition for translation.
Functional Requirement
When saving a new translation (TRL3) the user will then select the language pack they wish to base the new language from, the list of options will be filtered by those matching either the language, country, or the default en_US. Once the selection is made the application will create the default structure for the new language.
NTRL2. Export a Language Pack
User Story
The system will allow translators to export all relevant fields and strings to a file type that allows them to parse the values for translation.
Functional Requirement
When the user selects the installed language they require the user interface will show an 'Export' button at the bottom of the user interface. Clicking this button will allow the user to select a location where they wish to export the files to. Exported files will be in a specified format which can then be processed using open source translation editing tools.
NTRL4. Submit New Translations to Repository
User Story
The system will provide a convenient method for a new Translation to be submitted to a central repository for distribution to the community and implementers.
Functional Requirement
Where a new language pack is created by a partner/implementer the application will provide a means for the Translator to submit the new language pack to the Openbravo ERP Language Pack repository. This action will be through the application user interface under the Repository tab.
BPTRL3. Updating a Language Pack in the Application
TRL6.1. Refine an Implemented System Language
User Story
The system will enable a qualified user to amend translations within the application interface.
Functional Requirement
A Translator will select the Translation role. In this mode the user will have the ability to navigate through the application check the user interface in an interactive mode that will allow the user to modify the text displayed in the user interface. By clicking an icon in the toolbar (which will only be visible to Translator role users) the user will view a table of field labels and their translations within the application. These translated values will be editable within the grid. The user will then confirm or cancel the changes at the bottom of the form to store the results within the application, if the changes are confirmed they will become live within the application immediately.
TRL6.2. Retrieve Updates to Language Packs
User Story
The system should provide a mechanism that allows a qualified user to retrieve updated translations provided by other implementers/translators.
Functional Requirement
Under the repository tab in a language screen the Translator will be able to view those values that have been updated in the repository but not deployed into the application. This screen will show information on the quality of the update, and the difference to the application value.
RTRL1. Accept Translation Updates
User Story
The system will allow implementers of Openbravo ERP to submit updated translations to the central repository from within the application.
Functional Requirement
The repository tab will show locally modified values with the selection option to forward these updates to the central repository where they can be rated/scored by the community.
TRL9. Delete translation texts with their parent original text
User Story
The system will allow an authorised user to delete an element from the application and by doing so will also delete the translations for that text also. The translation text should not stop a valid deletion process.
Functional Requirement
At present in the application it is not possible to delete a TextInterface item with first explicitly deleting the translation children. It should be possible to delete the TextInterface and have this delete cascade through any existing translation items in the application.
BPTRL4. Repository of Language Packs
OTRL1. Translation Repository
User Story
The system will provide a central repository that allows Openbravo ERP implementers access to submit and retrieve translation packs and updates.
Functional Requirement
The language pack repository will hold headline information relating to all current existing translations within the Openbravo ERP framework. This headline information will be retrieved when requested by client installations to allow decisions to be made on which translation to retrieve.
Within these translations there will be a reference to the files which form the content of the translation.
RTRL2. Score/Quality Rate Translations
User Story
The system will provide a mechanism that allows the community and Openbravo ERP to rate a translation (new or update) for quality and suitability for implementation.
Functional Requirement
Each translation will hold statistical information to show the completeness and coverage of the translation. Based on this information a translation will be given a status which can be used as a guide to the suitability for implementation. This information will be made available within the translation header information to further aid the client installation administrator to make decisions on which language to install.
RTRL3. Publish New/Updated Translations
User Story
The system will provide a mechanism to enable translations (new and updates) to implementers of Openbravo ERP. This mechanism will include the quality/score for the translation to allow the implementer to decide if they wish to implement the translation into a live installation.
Functional Requirement
BPTRL5. Migration of Language Packs
BPTRL6. Multiple Language Support
MLS1. Define elements for Multiple Language Support
User Story
The application will provide System Admin users with the ability to define elements of the business data for MLS.
Functional Requirement
Within the application there are elements of Business Data (e.g. Products, Reports, Payment Terms) that should be translated into other languages for partners who use languages other than those defined for the application user interface. The System Admin should have a method to mark these table items as business data for the purpose of creating translations for them. Multiple Language Support can be defined for languages irrespective of whether they are defined as System Languages.
Elements included in Multiple Language Support by default are:
- Activity
- Country
- DocType
- Greeting
- Project
- ProjectType
- Products
- Payment Terms
- Region
- Sales Region
- Service Level
MLS2. Export MLS Business Data
User Story
The system will allow a Translator to export all 'Business Data' elements within the application marked for MLS to external files in a format that allows the translator to create translations for these files.
Functional Requirement
Add functionality to the Language window that allows the Translator to be able to export Business Data for the purpose of creating translations of the data. The export functionality will follow the same workflow as exporting application languages.
MLS3._Enable_MLS_Data_Input_In_Native_Language
User Story
The application will enable a user to enter data into a window in their native language and the application will ensure that the data is persisted in the application in both the default table and the translated language table.
Functional Requirement For Multiple Language Support to work efficiently a user should be able to enter data into the system in their native language and for this data to then be persisted in the application in such a manner that it conforms to the standards of the system. In this case that means that the entry created in the alternative language (non Base Language) will be used as the default entry in the Base Language as well as creating the entry in the MLS language. At a later point the Base Language version can be edited if required, as well as translated in other MLS languages.
EXTRL1. External Document Translation
User Story
The system will allow translation of external documents into languages other than those defined as available in the user interface. A user should be able to create a document in the language of a customer other than those defined as system languages.
Functional Requirement
Extend the functionality for MLS1 and MLS2 to include the creation of translations for specific documentation produced by the application. This involves translating the terminology, labels, headings, and content of defined documents. It is also necessary to define the language in which the document will be produced in relation to the partner for whom the report is targeted.
Default external documents to be included in Multiple Language Support are:
- Purchase Order
- Sales Order
- Purchase Invoice
- Sales Invoice
BPTRL7. Language Pack Installation at Install
INSTRL1. Install languages during installation
User Story
The system will allow the installation of other languages during the installation process.
Functional Requirement
During the process of installing Openbravo ERP it should be possible for the installer to select a language, other than the base language, to be installed at the same time. This process will then retrieve the language pack content and install the language pack so it is available to be used from the beginning.
INSTRL2. Install multiple languages during installation process
User Story
The system will allow the installation of multiple languages during the initial installation process of Openbravo ERP.
Functional Requirement
Extend INSTRL1 to be able to select and install multiple languages at the time of installing the application. All language pack content should be retrieved and made available for selection by users.
User Interface Mockups
Language Window - Edit Mode
| Tab | Level | Parent Tab |
|---|---|---|
| Language | 10 | |
| Repository | 20 | Language |
| Local | 30 | Repository |
| Remote | 30 | Repository |
Language Window - Locating a translation
Language Window - Installing a translation
Language Window - Exporting a translation
Language Window - Importing a translation
Editing Translations - Updating translations in the User Interface
Non-Functional Requirements
Currently there is a competing product that only takes 8 clicks to install and enable a new language pack in the application. The goal of this development should be to match this number.
Loading of a user interface element in a translated format should take no longer than the acceptable standard for Openbravo ERP. Currently this is set at less than a second to load the page.
Installation
Installation of an existing language pack should not involve the need to go outside the application interface to download, install, and enable the language in the application.