Projects:Translation Management/Technical Documentation

Contents 1 Introduction 2 Overview 3 Scope 4 Ubiquitous Language 5 Technical Implementation 5.1 Objects 5.1.1 Entities 5.1.2 Processes 5.2 Context 5.2.1 Repository 5.2.2 Openbravo ERP 5.2.3 Communication Layer 5.2.4 XMLEngine 5.3 Model 5.4 Packaging 5.5 Creation and Definition of a Language 5.6 Source Existing Translations 5.7 Initial Language Import Implementation 5.8 Enable A New Translation 5.8.1 HTML 5.8.2 XML 5.8.3 Page Generation Implementation 5.9 Translation Repository Implementation 5.10 Translating Files Implementation 6 Appendices 6.1 Appendix A. UML Diagrams 6.1.1 Translation Util library

Introduction

This document outlines the technical specification for the first phase of the implementation of the improved Translation Management process. The scope for this document is outlined below.

Overview

The technical specification contained herein is defined to create the base functionality for translation management in Openbravo ERP. This base implementation will be built on and extended in the remaining two iterations of this project.

The main goal here is to provide a methodology and framework for implementation which is as modular and independent in relation to the varying contexts of the solution. All touch points between the different context areas should be through a single access point and dependencies should be as minimal as possible.

Scope

TRL1 - Language Creation/Definition

TRL2 - Source existing translations

TRL4 - Importing a New System Language

TRL5 - Enable a New System Language

OTRL1 - Translation Repository

NTRL3 - Translating Files

Ubiquitous Language

• Translation - A translation is a language/country combination in the format ll_CC in line with ISO standards. As an extension of the Translation it can be defined with a suffix to specify the translation as a variation of the specified language/country combination e.g. es_ES_nav
• Translation Status - translation status is a description of the quality and completeness of the content of a translation. It includes :
  • Status - Alpha/Beta/Release
  • TranslatedBy - person(s)/organisation(s) that created the translation
  • Statistics - a percentage representation of the quantity of values translated within the language pack
• Language Pack - A language pack is a group of files containing the translated text in a single language/country combination for Openbravo ERP. A language pack will be linked to a specific translation
• Installation - Installation is the process of deploying a language pack into the structure and format for use in Openbravo ERP
• Translation Repository - A repository is a location which holds multiple language packs for Openbravo ERP
• System Language - A system language is a language that is enabled for users to select in the preferences. To qualify as a system language it would include translation of the meta data of the application including user interface labels
• Enable - To enable a Translation is to make it available for use by users of the application
• Import - Importing is the process of bringing something into the application
• Language - language is the dialect and is defined in the ISO standard 639-1
• Country - country is the country as defined in the ISO standards 3166-1 and 3166-1-alpha-2

Technical Implementation

Objects

Entities

• Translation
  • Purpose: main object in the translation hierarchy which will link to other objects detailed below.
• TranslationIdentifier
  • Purpose: Used to identify the translation based on language, country, version, and qualifier. A Translation in a specific country/language combination can be modified and saved under a different qualifier.
• TranslationStatus
  • Purpose: Holds relevant information on the status and completeness of the translation and defined by Openbravo
• LanguagePack
  • Purpose: Contains a collection of translation files consisting of file names, location
• Repository
  • Purpose: Connection information for accessing the repository for the language pack
• Country
  • Purpose: ISO listing of recognized country codes and their plain English name
• Language
  • Purpose: ISO listing of recognized language codes and their plain English name

Processes

• TranslationSearch
  • Purpose: Provides a standardized object which can be used across implementations for searching and locating translations.

Context

Repository

• TranslationDetails
• TranslationFiles

Openbravo ERP

• ApplicationFacade
  • Purpose: provides methods for searching and retrieving translations from the repository
• TranslationInstall
  • Purpose: Provide methods to install translations into the application once the files and information has been retrieved.

Communication Layer

• RepositoryFacade
  • Purpose: methods for retrieving files and information from the repository for the chosen translation
• TranslationAdapter
  • Purpose: acts as an adapter between the ApplicationFacade and RepositoryFacade to reduce the dependencies between the two.

XMLEngine

• TranslationFactory
  • This is the new implementaion that will be responsible for retrieving and populating the generated html document with the relevant translated or original text.

Model

Packaging

• OBTranslation library
• src-trl
• src/org/openbravo/??

Creation and Definition of a Language

This is perhaps the most work in the rewrite of this process, given that there is a new level of automation to the saving and creation of the language while removing other aspects of the current process to make the whole process more intuitive and simpler.

Source Existing Translations

Initial Language Import Implementation

Import to Database

The existing process of importing translation files into the application takes care of populating the database with the relevant entries, this includes populating the AD_TEXTINTERFACES_TRL table. Therefore there is nothing to then stop us dynamically calling the translated text from the database without compiling. Proposal is that this process will not be changed dramatically in function as it fulfills requirements for providing the data required to dynamically populate the web pages.

Enable A New Translation

HTML

Currently within a WAD generated window the meta-data for a label field is as follows

<td class="TitleCell" id="IsActive_lbl_td">
  <SPAN class="LabelText" id="IsActive_lbl">Active </SPAN>
</td>

The aim is to provide a simple implementation that will enable the XMLEngine to dynamically interpret the users current language to configure the html complete with translated text.

XML

Currently within the XML document for each page there are the following entries for each field

<FIELD id="IsActive" boolean="checked" withId="paramCheck">IsActive</FIELD>

with the language passed to the document through

<FIELD id="AD_Language" attribute="value">AD_Language</FIELD>

Page Generation Implementation

WAD Generated Windows

Using the combination of Field Id and the Label Id we can dynamically populate the label value. The id for the label should be the same as the id for the field but with _lbl suffixed at the end of the id. This allows access to the required labels without having to provide additional information in the XML document or change the schema for the HTML document.

Sourcing the translation

The following query can be used to identify translations for labels within the WAD generated windows.

SELECT * 
FROM AD_ELEMENT element
	INNER JOIN AD_ELEMENT_TRL trl ON element.AD_ELEMENT_ID = trl.AD_ELEMENT_ID
WHERE 
	element.name like 'Request User' --where 'Request Folder' is the text in the label field.
	OR element.columnname like 'RequestUser' -- where 'RequestUser' is the field id value in the xml file

the where clause can use wither the labelid with the suffixed '_lbl' removed or the field id from the XML document. Field id value would simplify the process.

Manually Created Windows

Sourcing the translation

The following query can be used to identify translations for labels within manually created HTML files.

select inter.*, interTRL.*
from "TADTRL"."AD_TEXTINTERFACES" inter
	INNER JOIN "TADTRL"."AD_TEXTINTERFACES_TRL" interTRL on inter.AD_TEXTINTERFACES_ID = interTRL.AD_TEXTINTERFACES_ID
where inter.text like '%Format file%'
	AND (inter.filename like '/org/openbravo/erpCommon/ad_forms/FileImport.html' OR inter.filename is null)

Need to provide contingency to provide default text for any values that have not been translated.

Translation Repository Implementation

The repository will be accessed through a communications layer in the form of a web services implementation. This implementation will store information regarding the location of the repository, the list of relevant files contained in the repository, and information regarding the status of the translation.

The communications layer is responsible for receiving the request from the application to locate a translation and then return the relevant status information based on the search object.

The user will then make a selection from this list and this request will pass to the communications layer to package the appropriate files and return them to the requestor where they can be unpacked and installed by the application.

For this phase their is no requirement to be able to write information from an application directly to the repository. The repository is to be read-only for requests from the application/installation.

A convenient means for the repository administrator to update the repository information is to be decided.

To avoid duplication of effort and excessive development time it is preferable to reuse existing implementations of this type that already exist within the Openbravo server architecture. Can this be linked in with the heartbeat server??

Translating Files Implementation

Appendices

Appendix A. UML Diagrams

Translation Util library