Outdated documentation

You are looking at the documentation for an older release. For the latest information, please see current release documentation.

Custom Language File

To use this tutorial you need file system and command line access to the server where OTRS is running.

Note

This feature is only available to On-Premise customers. If you are a Managed customer, this feature is taken care of by the Customer Solutions Team in OTRS. Please contact us via support@otrs.com or in the OTRS Portal.

OTRS can be localized into other languages than English. The language files are stored in .pm files under the $OTRS_HOME/Kernel/Language/ folder. There are three types of language files:

Framework language file

The files named based on a language code and optional dialect code separated by an underscore character (for example de.pm for German language file or en_CA.pm for the Canadian English language file) contain the translation of the core system. These files are part of the released package and they are being updated time to time with the translations made on OTRS Translation Portal.

Do not edit these files manually. They will be overwritten during the next version update.

Package language file

Packages like ITSM packages or feature add-on packages have own language files using the following naming convention: language code and optional dialect code followed by the package name separated by underscore characters (for example de_OTRSServiceManagement.pm for German language file or en_CA_OTRSServiceManagement.pm for the Canadian English language file of the OTRSServiceManagement package).

Do not edit these files manually. They will be overwritten during the next version update.

Custom language file

Custom language files are not part of the system. You have to create it manually and put it to the language folder. The name of the custom language file should be a language code and optional dialect code followed by the word Custom separated by underscore character (for example de_Custom.pm for German custom language file or en_CA_Custom.pm for the Canadian English custom language file). Since this file is not part of the release package, this will not be overwritten during version updates.

In a system where all kind of language files are present, the framework language file is loaded first then the package language files are loaded in alphabetical order and finally the custom language file is loaded. This ensures that the translations from the custom language file can override any previous translations.

There are two kind of usage of the custom language file:

1. To add translation to system resources created or changed after the installation.
2. To customize the existing translation.

During the configuration phase of the system the created or modified resources can contain new translatable strings like names, descriptions or any other attributes of the following resources:

• Calendars
• FAQ Category
• System Configuration
• Dynamic Fields
• Process Management
• Priorities
• Services
• Service Level Agreements
• States
• Types
• Customers
• Customer Users

It is recommended to always use English texts for the resources above and translate them using the custom language file even if the system is designed to be used in a specific language.

When the resources have been added to the system, you have to collect the translatable strings manually and you have to add them to the custom language file.

This example shows a system where a new drop-down dynamic field with translatable options and a new ticket state have been added. Additionally an existing translation has been changed.

The German custom language file should look like this:

# --
# Copyright (C) YEAR, https://your-company.com/
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (GPL). If you
# did not receive this file, see https://www.gnu.org/licenses/gpl-3.0.txt.
# --

package Kernel::Language::de_Custom;

use strict;
use warnings;
use utf8;

sub Data {
    my $Self = shift;

    # School dynamic field options
    $Self->{Translation}->{'middle school'} = 'Mittelschule';
    $Self->{Translation}->{'high school'} = 'Oberschule';
    $Self->{Translation}->{'University'} = 'Universität';

    # Ticket state
    $Self->{Translation}->{'closed with workaround'} = 'provisorisch geschlossen';

    # Override existing translation
    $Self->{Translation}->{'Internal News'} = 'Firmennachrichten';

    push @{ $Self->{JavaScriptStrings} // [] }, (
    );

    return;
}

1;

The first section contains copyright and license information. Since OTRS is licensed under GNU GPL version 3 it is recommended to apply the same license to the custom language file. Do not forget to change the year and the copyright holder in the second line.

The next section contains the package path which should be the relative path from the OTRS home folder and the name of the custom language file without the file extension. In the example above this is Kernel::Language::de_Custom. If you create the custom language file for another language you have to change the language prefix in the last segment of the path.

The most important section is the translation entries. Each entry contains the English string as key and the translation of the target language as value. It is recommended to group the entries and add a comment (a line starting with # character) which explains where the strings come from. This facilitates the maintenance of the custom language file.

It is possible to override the existing translation of the framework. In our example we override the German translation of Internal News with Firmennachrichten instead of the original Interne Nachrichten. To do this you have to search for the original string in the German language file (de.pm) then copy the original string to the custom language file and add different translation.

Any character can be in the strings but the apostrophe character has to be escaped as \' like don\'t because this character is used as enclosing character.

The language files for the new interface are now part of the built application (static JSON). When you add a custom language file to the file system, you need to rebuild the application for the change to be considered. To trigger the rebuild, restart the server with the --deploy-assets option:

otrs> /opt/otrs/bin/otrs.WebServer.pl --deploy-assets

During the build process, the language files will be refreshed and will take any *_Custom.pm into account.