Language handling

Translation and language maintenance software

For translations and maintenance of language keys, we decided to use oTrance, the Online Translation Center (available under GPLv2) and installed it on

Download language packs

You cannot help with language translations? No problem. Simply go to to get logged in as a guest.

If you need help with the translation software, please refer to this wiki page where the handling with a guest account is explained:

If you are familiar with using GitHub, you can also check out for available languages. will export to this repository regularly.

Additionally, we offer downloads of single language packs (per language) marked as “OK” or “perfect” from the download area of this site.

Help translating

If you want to help translating and/or maintaining the languages, please register at After that, please wait for the system administrator to activate your account before you can start translating.

If you want, you can also maintain your translations with this tool. The advantage is that there will be no hassle with character encoding or possible mistakes – for example, if you forgot a comma or a quote.

If you have already files translated into your language, please send them to [email protected] We will import them into the system and make them available to the community.

If you need help with the software, please refer to this wiki page where is explained how to use oTranCe as a translator:

For OXID specific translation questions and announcements please refer to

But first, you might want to watch this screen cast about working with oTranCe as a translator:

Installation of new languages in OXID eShop

  1. Download the language packages from oTranCe.
  2. Extract them and upload them to the according paths of your shop installation.
  3. Go to the admin panel of your OXID eShop installation -> Master settings -> Languages. Add a new language and enter the abbreviation according to the one you found in oTranCe.
  4. In admin panel, go to Service -> Tools and push the “Update views” button.
  5. Clear the tmp/ folder in your installation and refresh your page.
  6. You are done 🙂

Language maintenance for German and English

OXID will take over the language maintenance for German and English as it will be delivered with each standard copy of OXID eShop in any edition. Any other translations can be contributed, maintained and downloaded by community members for free use under GPLv3 license. With every stable release of OXID eShop, OXID will update the oTranCe database with both languages. You don’t have to register at for helping with German or English 🙂 If you found something strange like a misspelled word or another typo in one of both languages, please simply open up a bug for it at or send a pull request via GitHub.

Integration with GitHub

oTranCe is able to export the ready-to-use language files to any SVN as well as to GitHub:

Here, we added map.php files, flags as well as transliteration lists. These files are also provided when downloading the package from

File structure

├── application
│   ├── translations
│   │   ├── de
│   │   │   ├── lang.php
│   │   │   └── translit_lang.php
│   │   ├── en
│   │   │   └── lang.php
│   └── views
│       ├── admin
│       │   ├── de
│       │   │   ├── help_lang.php
│       │   │   └── lang.php
│       │   ├── en
│       │   │   ├── help_lang.php
│       │   │   └── lang.php
│       └── azure
│           ├── de
│           │   ├── lang.php
│           │   ├── map.php
│           │   └── theme_options.php
│           ├── en
│           │   ├── lang.php
│           │   ├── map.php
│           │   └── theme_options.php
│── out
│   └── azure
│       └── img
│           └── lang
│               ├── de.png
│               ├── en.png
└── setup
    ├── de
    │   └── lang.php
    ├── en
        └── lang.php

Digging deeper – which files to touch for translations

On we already use file templates for export so the right format. The exact number of files and the right folder structure will be available in the download packages.

The following points are just for your information.

Translating the store front, using the standard template “Azure”

If you want to translate the store front using “Azure” or a derived work from it, you have to translate the following files:

  • /application/translations/{LOCALE}/lang.php
  • /application/view/azure/{LOCALE}/lang.php

Translating the administration area

If you want to translate the administration area you have to translate the following files:

  • /application/views/admin/{LOCALE}/lang.php
  • /application/views/admin/{LOCALE}/help_lang.php
  • /application/views/azure/{LOCALE}/theme_options.php

Translating the setup

If you want to translate the setup routine you have to translate the following files:

  • /setup/{LOCALE}/lang.php

Other language related files

There’s a number of files related to languages but not to translations. These files are already implemented in the download packages on


Of course, a language needs a flag, doesn’t it 🙂 That’s why we put a flag into the language pack the first time we get in touch with that language. This can be when a translation is started, when we get language files or even when somebody registers for this translation at

The size of the flag is theme dependent, that’s why it was put to the folder /out/{theme}/img/lang/. So an image file with a language flag for the theme “azure” can be found at /out/azure/img/lang/{locale}.png and is adjusted to 14 x 10 px.

If you want to translate into a new language not listed yet we’d appreciate if you could provide the flag either by a pull request on GitHub or by sending it to [email protected]

Transliteration lists

Why is a transliteration needed and what it is used for?
Well, in some languages you don’t just use pure Latin characters but also so called “Umlauts” for pronouncation purposes. In case these “Umlauts” appear in the title of a product, the class oxseourl tries to form a proper URL from it.

Just an example: If you sell belts, the German translation for it would be “Gürtel”, using the Umlaut “ü” in the product title. If you didn’t enter any transliteration, oxseourl would swallow the “Umlaut” and the URL would go like . But who the heck of your potential customers is googling for “grtel”? So the correct URL should be as the search engines would understand “ue” for “ü”. For this reason, there has to be a transliteration array telling OXID eShop how to transliterate special characters like “ü” shall become an “ue” in the URL which is applicable.

Talking about non-Latin-based languages, it becomes even more complex. Let’s talk about Russian using the Cyrillic script. Here, the transliteration list is pretty much longer, containing “я”, “ю” and “ж” which can be transformed to “ya”, “yu” and “zh” in the URL.

In this manner, Cyrillic is still pretty simple as it uses just different characters. Another challenge are Asian languages as their scripts describe syllables as well as entire words. We are not really sure if pinyin for Chinese, for example, can resolve this 😉

Until OXID eShop v4.5, transliteration lists have been stored in the OXID eShop database. Maintenance was held inside the admin panel: Master settings -> Core settings -> SEO -> Characters which are replaced in SEO URLs.

In OXID eShop version 4.6, we stored transliteration lists inside the language files where needed. In version 4.7/5.0, the transliteration lists disappeared from the admin panel and will be stored separately from the general language files but at the same level as translit_lang.php, for example:

We’d be glad if you could share your transliteration lists with the community. Simply send a pull request via GitHub or drop an email to [email protected] if you’re not familiar with version control systems.

Language key mapping – what is map.php

With the introduction of theme handling in OXID eShop 4.5.0, there were different language strings for each theme. We were using two different theme-dependent language files for the basic and azure themes. To make this system more flexible and to avoid redundancy and repetition in language constants, we moved to a generic language file which is valid for all themes (even self-made themes) in version 4.5.1.

By this, it is possible to use different language strings per theme. Of course, the override functionality is still available for all of these files, so your system will remain easily updatable as long as you make use of the cust_lang.php file.

We implemented a mapping file to enable mapping between the generic language constants and the theme-specific constants. This is to ensure maximum flexibility when updating the system. In most cases, the language constants from the azure theme will be simplified and used as the basis for generic constant names.

Example: You will notice that there are many different definitions for email in both, your custom and azure theme, like the examples below:


The new generic language file has only one constant for email:

EMAIL => ‘email’ 

The mapping array will take care of defining the basic and azure theme constants’ relationships with the generic language file:


If a theme needs to change specific constants, it can do this by redefining the constants inside the theme-specific language file:

FORM_PRICEALARM_EMAIL => ‘email address’

Language override system – cust_lang.php

For your own customizations, you can use custom language files per theme (remember that these will be excluded from update packages as well as from language packs). And if you’re a user of OXID eShop Enterprise Edition, there is also another override level for your subshops.

To summarize, the priority for language handling will be like this:

custom language file -> theme language file -> subshop language file -> general language file

2 replies

Trackbacks & Pingbacks

  1. […] translation software we formerly used, oTranCe, would not have updates any longer, and with ongoing PHP updates, we ran into more and more “challenges”. That is why we […]

  2. […] For OXID eShop version 5.1, the map usages were removed from all templates to avoid confusion. The heavy usage of maps cluttered the system and it became hard to track all the changes and translation usages. The functionality is still there and can be used if you feel fancy; you’ll find more information here: […]

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published.