4PSA DNS Manager 3.7.0 Translator's Manual For more information about 4PSA DNS Manager, check: http://www.4psa.com Copyrights 2002-2010 Rack-Soft, Inc.
Translator's Manual Manual Version 48807.9 at 2010/03/10 09:24:23 For suggestions regarding this manual contact: docs@4psa.com Copyright 2002-2010 Rack-Soft, Inc All rights reserved Distribution of this work or derivative of this work is prohibited unless prior written permission is obtained from the copyright holder. 4PSA is a Registered Trademark of Rack-Soft, Inc. Plesk is a Registered Trademark of SWsoft, Inc. Linux is a Registered Trademark of Linus Torvalds. RedHat is a Registered Trademark of Red Hat Software, Inc. FreeBSD is a Registered Trademark of FreeBSD, Inc. All other trademarks and copyrights are property of their respective owners.
Table of Contents Preface... 4 Who Should Read This Guide... 4 Overview... 4 Chapter 1. What is a Language Pack?... 5 Components of the Language Pack... 5 Location of the Language Files... 6 Naming Conventions... 6 The Interface Language File... 7 Tips... 7 Structure of the Interface Language File... 8 Chapter 2. How to Create a Language Pack?... 12 Get the Language Pack Component English Files... 13 Translate the Interface Language File... 13 Compile the Language Pack... 13 Install the Language Pack... 14 Distribute the Language Pack... 14 Chapter 3. Get Support... 15 Chapter 4. Contact Information... 16 Resources... 17
Preface Who Should Read This Guide This guide should be read by anyone interested in translating 4PSA DNS Manager. You do not have to read the entire manual in order to perform a translation. However, this guide should answer any questions you might have about the process. It can also help you solve problems you might experience with the procedure. Overview This document is a guide for creating and installing language packs for 4PSA DNS Manager. It describes the structure of the language files, provides instructions on how to create a language pack in the chosen language and how to install it on the server. Note All 4PSA DNS Manager translations must be verified and centralized by 4PSA. Please send them to <docs@4psa.com>. Chapter 1, What is a Language Pack? describes the components of the language pack and the structure of the language files. Chapter 2, How to Create a Language Pack? explains the steps needed to create and install a language pack. 4
Chapter 1 What is a Language Pack? The language pack is a group of files that define the text displayed in the 4PSA DNS Manager interface as well as the content of the online help. Components of the Language Pack The two main components of the 4PSA DNS Manager language pack are: The interface language file This file defines all the text messages, labels, tool tips, etc. displayed in the 4PSA DNS Manager interface The online help directory This directory contains the help pages that can be accessed from the 4PSA DNS Manager interface, by clicking the Help link. 5
Location of the Language Files The language files can be found on the 4PSA DNS Manager server at: <DNSMANAGER_ROOT_D>/admin/htdocs Note <DNSMANAGER_ROOT_D>is the default installation directory for 4PSA DNS Manager. <DNSMANAGER_ROOT_D> is defined in /etc/dnsmanager/dnsmanager.conf. Inside the directory <DNSMANAGER_ROOT_D>/admin/htdocs you will find two sub-directories: help - It contains the help files. These files are grouped into sub-directories, based on the user account they can be viewed from. On a freshly installed 4PSA DNS Manager server, you will find the following subdirectories for the English help files: en/admin/ en/client/ Note You will also find some additional subdirectories that are not part of the language pack and that must not be translated: css - Contains the stylesheet for the help pages. images - Contains the icons and graphics used in the help pages. js - Contains a JavaScript file that controls the table of contents functionality. language - It contains interface language files. On a freshly installed 4PSA DNS Manager server, you will find only en.php, the language file for English. Naming Conventions The files included in a language pack follow specific naming conventions, as described below: The interface language file is named after the two letter code of the language, as specified by the ISO 639 1 standard. For example, the interface language file in English is named en.php. 6
The help directory is named after the two letter code of the language, as specified by the ISO 639 1 standard. For example, the directory for the help files in English is named en. The Interface Language File The interface language file is a.php file, so it must follow the syntax rules of the PHP programming language. The language file is a sequence of array element definitions. Each definition contains two parts. The text that should be translated is the text on the right side of the equal sign (=) and enclosed in single quotes ('). Example of an element definition: $msg_arr['btn_help'] = 'Help'; where btn_help is called a keyword and Help is the text that must be translated. Tips When translating the interface language file, keep in mind the following: Translate only the text on the right of the equal sign Make sure you do not translate keywords. This can accidentally happen if you use the Search and Replace All function available in most text editors. Escape single quotes If the text contains single quotes, you must insert a backslash (\) in front of the quote, like in the example below: 'Don\'t forget to escape single quotes in this text.' Do not translate template fields The language files also contain some special elements called template fields. They come in the form of text surrounded by braces ({template filed}). These fields are automatically replaced by context specific information. Below is an example of a language file entry containing a template field: $msg_arr['java_send_ok'] = 'The email was sent to {mail}.'; In the 4PSA DNS Manager interface, this entry can be displayed as: The email was sent to John Smith.. 7
Caution Deleting or even modifying these template fields will result in incomplete phrases being displayed in the 4PSA DNS Manager interface and may cause undesired behavior. Use a text editor with PHP error checking capabilities It is essential that the language interface file does not contain PHP syntax errors. To make sure that the translated file is valid, you can use a text editor that can check the PHP code and find errors. There are many editors with this capability, on a commercial as well as freeware, shareware or open-source basis. One example is jedit, a free and powerful text editor [1]. The PHP parser function can be installed as a plug-in [2]. Structure of the Interface Language File The content of a language file is structured in several sections. Each section corresponds to a type of element of the 4PSA DNS Manager interface. Here is an alphabetical list of these sections: //button names //context help messages //HTML alert titles and bodies //JavaScript messages //left frame section //legend section //soap //tab titles //table headers //text labels //warning and error messages The Header Section Each language file should contain a header with the following information: 8
The language of the translation The person responsible for the translation of the file The email address of the person responsible for the translation The 4PSA DNS Manager version number for which the language file was created Below is an example of a header for an interface language file in English: // Local file for English language // Maintained by Rack-Soft, Inc (www.4psa.com) // docs@4psa.com // 4PSA DNS Manager 3.7.0 Note The header section is required in all language files. The Button Names Section This section contains the text displayed on the buttons available in the 4PSA DNS Manager interface. This text is also displayed when the mouse pointer hovers over a button (also known as alternative text ). The array keys for the entries in this section begin with the keyword btn_, followed by the message description. The Context Help Messages Section This section contains the help messages displayed in the Help area located in the left frame of every 4PSA DNS Manager interface. The array keys for the entries in this section begin with different keywords, as described below: b_ for entries containing the help message displayed when the mouse pointer moves over a button i_ for entries containing the help message displayed when the mouse pointer moves over an icon l_ for entries containing the help message displayed when the mouse pointer moves over a link The HTML Alert Titles and Bodies Section This section contains the text displayed in HTML alerts. A HTML alert is a error or warning message displayed at the top of the page. The array keys for 9
alert titles begin with the keyword mt_. The array keys for alert titles begin with the keyword mb_. The JavaScript Messages Section This section contains the text related to the Javascript sections of the 4PSA DNS Manager. The array keys for the entries in this section begin with the keyword java_, followed by the message description. The Left Frame Section This section contains the entries in the left frame area of the 4PSA DNS Manager. The array keys for the entries in this section begin with the keyword lf_, followed by the message description. The Legend Section This section contains the text displayed in the text areas surrounded by a border in the main area of the 4PSA DNS Manager interface. The array keys for the entries in this section begin with the keyword lg_, followed by the message description. The SOAP Section This section contains the text used in SOAP API messages. The array keys for the entries in this section begin with the keyword soap_. The Tab Titles Section This section contains the titles of tabs in a multi-tab page. The array keys for the entries in this section begin with the keyword tab_. The Table Headers Section This section contains the text displayed in the header of any table that appears in the 4PSA DNS Manager interface. The array keys for the entries in this section begin with the keyword header_, followed by the message description. The Text Labels Section This section contains the text displayed in the main area of the 4PSA DNS Manager interface. This text is not included in any other section of the language 10
file (independent text). The array keys for the entries in this section contain a short description of the text that will be displayed. The Warning and Error Messages Section This section contains warning and error messages displayed in the main area of the 4PSA DNS Manager interface. The array keys for the entries in this section contain a short description of the error that was encountered. 11
Chapter 2 How to Create a Language Pack? When translating the 4PSA DNS Manager interface, you have two options: Translate only the interface language file en.php. Since the online help is quite large, you will probably want to translate the interface messages and view your translation in the 4PSA DNS Manager interface. This approach is described below. Translate both the interface language file and the help files. Caution It is not recommended to translate the HTML files available in the directory <DNS Manager_ROOT_D>/admin/htdocs/help/en because it will be much more complicated to update any changes that appear between product versions. The help files are generated automatically using XML/ XSLT technology. If you want to translate the online help, please contact <docs@4psa.com> to obtain the XML source document of the online help and more instructions. 12
If you want to translate only the interface language file, follow these steps: 1. Get the language pack component files in English. 2. Translate the interface language file. 3. Compile the language pack. 4. Install the language pack. 5. Distribute the language pack. The standard 4PSA DNS Manager distribution comes with a couple of scripts that help you create and install language packs. These scripts can be found at <DNSMANAGER_ROOT_D>/bin/utils/. Below you can find more details on how to use these scripts. Get the Language Pack Component English Files 1. Change the current directory to: <DNSMANAGER_ROOT_D>/bin/utils/ 2. Run the script dnsmanager_lp_replicate.sh This script will ask you to enter the ISO code of the language for your 4PSA DNS Manager translation. 3. The script creates a new directory named language_packs/ <LANGUAGE_CODE> which contains all the files needed by the language pack. Translate the Interface Language File Translate the file created in the previous step: language_packs/ <LANGUAGE_CODE>/language/<LANGUAGE_CODE>.php. Note You can use your favourite text editor. However, make sure that the file is PHP valid (for more details, follow the Tips ). Compile the Language Pack 1. Change the current directory to: <DNSMANAGER_ROOT_D>/bin/utils/. 2. Run the script dnamanager_lp_create.sh The script will ask you to enter: 13
The ISO code of the language of the 4PSA DNS Manager translation. The name of the language of the 4PSA DNS Manager translation. The version of the 4PSA DNS Manager product corresponding to the translated language pack. Caution The script searches the current directory for a sub-directory named after the ISO code of the language. If you have skipped the first step ( Get the Language Pack Component English Files ), the script will display an error message because it cannot find the sub-directory <LANGUAGE_NAME>. 3. The script creates two files that can be used for installing the language pack: dnsmanager<product_version>_<language_name>.sh dnsmanager<product_version>_<language_name>.tar.gz Install the Language Pack To install the language pack you have two options: From the directory <DNSMANAGER_ROOT_D>/bin/utils/language_packs/ on your server. Run the dnsmanager<product_version>_<language_name>.sh script created previously. From the 4PSA DNS Manager interface. 1. Log in the 4PSA DNS Manager interface with the administrator account. 2. Go to the PBX» Languages» Add language page. 3. Upload the dnsmanager<product_version>_<language_name>.tar.gz file that was created previously. Distribute the Language Pack If you have created a language pack for 4PSA DNS Manager, please distribute it. Send it at the following email address <docs@4psa.com>. Note Please do not use other channels to share the language packs. 14
Chapter 3 Get Support For online help and support please visit the below areas: Knowledge Base: http://kb.4psa.com Help Desk Center: https://help.4psa.com Forums: http://forum.4psa.com Report Bugs: http://www.4psa.com/bugreport 15
Chapter 4 Contact Information Development office: Rack-Soft SRL DCL Office Building, 20-22 Bilciuresti Street, sector 1 Bucharest, 014012 ROMANIA Phone: 646-957-8997 (US), 0213130165 (Romania) Fax: 270-638-0988 (US), 0213130165 (Romania) E-mail: For purchasing and sales information, e-mail sales@4psa.com For partnership opportunities, e-mail channel@4psa.com For translations and localization, e-mail docs@4psa.com 16
Resources [1] jedit text editor. Go to download page. [2] PHP parser plug-in for jedit. Go to download page. 17