Language Support
Introduction
With the introduction of version 2.4, Reportico provides multiple language support as follows :-
- Configuration options for handling different character encodings used within your database or in presentation to the browser.
Character sets such as UTF-8, Latin, ISO-8859-x, Windows-xxxx, Chinese GBK, and Japanese SJIS are supported. Level of support is dependent on your
combination of operating system and database.
- The ability to translate the core Reportico application into different languages by creating/maintaining language files
- The ability to provide translations for your database data strings by maintaining project language translation files
Note that PDF output in different languages is dependent on specific font requirements. See the section:q
For further details see the PDF Font and Language Support section.
Character Sets and Encoding within the Database
Depending on your type of database it may be necessary to specify a character set for fetching database data. This is true in many MySQL installations where the default character set for a database connection is LATIN1 but many databases store data in Unicode UTF8 format and others. If the data in the database is in, say UTF8 format, then Reportico must be told about this to alter its connection accordingly. Other databases may already provide data in the the desired encoding and there it is not necessary to specify an encoding. You can set the character set when you create or configure a project. By default, Reportico assumes no encoding and will therefore not run any special command on each connection to the database to set an expected encoding standard. If you are unsure of what to set this value to, then if you are in an English speaking country then leaving the default of None is probably ok, otherwise UTF8 is probably a good alternative to start with.
In the Create Project and Configure Project screens you can select your database encoding using the Database Character Encoding field.
The encoding can also be set manually for an existing project by editing the configuration file config.php which is found in the appropriate project folder under the projects folder. Just change the SW_DB_ENCODING value to be a value that you would pass to the standard SQL "SET NAMES" command which sets your encoding. Depending on the database, valid values include None, UTF8, EUC_CN, EUC_JP, EUC_KR, EUC_TW, GB18030, GBK, ISO_8859_5, ISO_8859_6, ISO_8859_7, ISO_8859_8, LATIN1, LATIN2, LATIN3, LATIN4, LATIN5, LATIN6, LATIN7, LATIN8, LATIN9, LATIN10, SJIS, WIN1250, WIN1251, WIN1252, WIN1253, WIN1254, WIN1255, WIN1256, WIN1257, WIN1258. With Microsoft SQL Server, UTF8 and PHP are not known for working easily, but should work in most scenarios, however may not work with other encodings.
Character Sets and Encoding in Output
Browsers also need to know what character set your reports are generating report output in. This in most cases will be the same as the format you are reading data in. So if you are reading from the database in UTF8 then you probably want to tell the browser that your output is UTF8. Using the default of noencoding will place no instructions in the browser header, which in many browsers means ISI-8859-1 european encoding. As with the database encoding, if you are unsure it is good to start with "No encoding" which will work for English speaking countries or the next to try would be UTF8 which is the most commonly used encoding in websites pages.
In the Create Project and Configure Project screens you can select your output encoding using the Database Character Encoding field.
The encoding can also be set manually for an existing project by editing the configuration file config.php which is found in the appropriate project folder under the projects folder. Just change the SW_OUTPUT_ENCODING value to be one of
None, UTF8, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8-I, ISO-8859-8, ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-12, ISO-8859-13, ISO-8859-14, ISO-8859-15, ISO-8859-16, GB2312, GBK, Shift_JIS, Windows-1250, Windows-1251, Windows-1252 Windows-1253, Windows-1254, Windows-1255, Windows-1256, Windows-1257, Windows-1258, Big5, GB18030, HZ, EUC-JP, EUC-KR, TIS-620.
Reportico Application Translations
The core Reportico designer application can be translated into different languages. All the text that makes up the Reportico Application is set up in language specific files held under the language folder. For each language there is an associated folder, for example en_gb for UK English. In each of these language specific folders, 6 translation files can be found :- languages.php (Contains translations of the languages supported), admin.php (Contains strings used in the administration page), menu.php ( contains strings displayed in project menus), prepare.php ( contains strings used in criteria entry mode ), maintain.php ( contains strings displayed in report design mode ) and execute.php ( contains strings displayed in report output ). By default Reportico comes with UK English and US English. You may create your own or download others from the Reportico site at http://www.reportico.org/swsite/site/downloads/. At the time of writing Reporting only comes with 3 other EXPERIMENTAL languages which can be found below the languages/packs folders.. these are French, Spanish and Chinese which are all highly experimental and produced by online translation engines. To use any of these languages move them up a level into the languages directory. If your language is not supported or your character encoding (see next paragraph) is not supported or the language is not linguistically correct then please feel free to submit a language pack to the Reportico site either by posting to the forum or by sending via email.
Since Reportico can generate web output in different character sets, the language packs under eahc language directory must all be in UTF-8. These will be converted to the output character set (if necessary) at run time. Having the output character encoding in UTF-8 has less of a performance hit. However, saying that, language packs in other character sets can be provided if placed in an folder under the language folder with an appropriate name. So for example, French could have translations in ISO-8859-1. Chinese could have translations provided in GB2312, GBK or BIG5 encodings as well as UTF-8. To cater for multiple encodings, each language folder may contain a folder for each encoding type each with their own set of translations. If no folder matching the used encoding is used then the default set of translations under the language folder itself is used which is the default of UTF8. So for example, the Chinese language folder cn_zh may contain a set of language files in Unicode UTF8 format by default, but other encodings such as GB2312 would have translations below cn_zh/GB2312 and BIG5 would appear under cn_zh/BIG5. So to recap, Reportico language packs all contain a set of translations by default in UTF-8 format in their top level directory. Any other encoded translations appear in their own folder named as one of ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8-I, ISO-8859-8, ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-12, ISO-8859-13, ISO-8859-14, ISO-8859-15, ISO-8859-16, GB2312, GBK, Shift_JIS, Windows-1250, Windows-1251, Windows-1252 Windows-1253, Windows-1254, Windows-1255, Windows-1256, Windows-1257, Windows-1258, Big5, GB18030, HZ, EUC-JP, EUC-KR, TIS-620
New language folders may be created under the language folder. Just create your language folder there named with the appropriate language code (you could copy the contents of the en_gb folder to get you started. Then edit each of the language files in your new folder and translate all the text on the right of the "=>" to your desired language. If you are creating your translations in Unicode UTF* format then the translations should appear below the language directory you created, otherwise they need to appear in their own encoding directory as detaild in the previous paragraph.
To change existing language text, simply navigate to the relevant language directory and edit the existing files.
The default language for your Reportico installation is prompted for when you run Reportico for the first time at the same time as you set the administrator password. This is stored in the SW_LANGUAGE configuration parameter found within the file projects/admin/config.php. This can be modified manually to any language relating to any language pack installed below the language folder. The language for the current session can be changed in the Administration page, but the default Administrator language must be set in the config.php after it has been set in initialisation.
Additionally a default language must be set for each report project. This is the language that will be used if a report user follows a link directly to the project report suite without going through the administration page - otherwise the administration page language will be used. The project language is set in the Create Project and Configure Project pages. The project language is stored in the SW_LANGUAGE configuration parameter found within the config.php of your report project folder. This can be changed at any point using the Configure Project page or by manually changing this parameter in the config.php file to a language as found under the main reportico language folder.
An option to change the current operating language is provided both in the Administration pane and in the Menu Page. If you want to limit the number of languages available or only work in one language then simply remove all the languages below the Reportico language folder that you are not interested in. If you remove all but one language then the language will not be prompted for since only one is available. There must be at least one language for Reportico to work!
Since Reportico reports may be executed directly or linked to via http url requests, it is possible to set the session operating language by specifying the URL language parameter language. Passing language=fr_fr will run a report or link to Reportico in French assuming the language exists.
User Data Translations
As well internationalisation support for the Reportico application, there is also translation support for Reportico user data, so that criteria entry labels, report descriptions, report output column header/trailer names, titles etc can be specified in several languages. That is a single Reportico project can be used by users from different countries. You only need to edit the file lang.php in your project and place all the translations you want in there. An example from the supplied tutorials is as follows :-
<?php
$g_translations = array (
"en_gb" => array (
),
"fr_fr" => array (
"Criteria" => "Critere",
"Film" => "Filme",
"Country" => "Pays",
"Film Category" => "Categorie Du Film",
.....
In the example above any criteria item, column header, trailer label named "Country" will appear in its French equivalent "Pays".
Note that currently report data showing in the body of the report are not translated, but support for this will appear in the near future.
Country Specific Date Pickers
The date picker available in Reportico (thanks to jQuery) can also take advantage of the system language. It will display the month and week elements relevant to the country. As long as your language is specified as one of the ones in the next section "Language Codes" it should work.
Note that currently report data showing in the body of the report are not translated, but support for this will appear in the near future.
Known language codes
The language codes used must correspond to those used in Linux systems as follows :-
af en_nz hu no ta
ar_dz eo hy pl th
ar es id pt_br tj
az et is pt tr
bg eu it rm uk
bs fa ja ro vi
ca fi ko ru zh_cn
cs fo kz sk zh_hk
da fr_ch lt sl zh_tw
de fr lv sq
el gl ml sr
en_au he ms sr_sr
en_gb hr nl sv
en_us hr nl sv
PDF Font and Language Support
Reportico makes use of both PDF geneartion libraries FPDF (www.fpdf.org) and UFPDF (http://acko.net/blog/ufpdf-unicode-utf-8-extension-for-fpdf/). Depending on the chosen PDF reporting font, one or the other will be used. FPDF is used to produce reports in an ASCII character set (an operates more quickly ) and UFPDF is a Unicode variant that is able to produce non-ASCII characters assuming a suitable font is provided. Users wishing to output their data in a non-English only character sets, which include characters not found in standard ASCII, should choose a Font which caters for their language. Users wanting non-standard fonts can import their own. Note that if the font supports many characters it can have quite an impact on the report generation time.
Note that if a UTF-8 font is used then the project output character set must be set to UTF-8 too. Reportico cannot calculate whether a PDF is UTF-8 or not.
Reportico comes with a small set of supported fonts.
For ASCII reporting (e.g. Latin character sets), Reportico comes with helvetica, times, courier and times fonts. Reportico comes with several Truetype Unicode fonts :- LiberationSans-Regular (good for most European character sets), Mothanna/Thabit for arabic support, WenQuanYiZenHei for Chinese support, japanese-gothic for Japanese support. Others will be added over time.
Using your own custom fonts
To load your own custom font from a Truetype font, go to the fpdf/font area and see the README.txt file in there for instructions. On a linux machine you should be able to got to the fpdf/font directory, copy a ttf font file in there and run sh makepdffont fontname-without-ttf-extension. This should create a fontname.php file. To use the font as a project default you can edit the config.php file in your project directory and change the parameter SW_DEFAULT_pdfFont to the name of your font (without the ttf extension). To set the font in a single report file edit the report in design mode, go to the Format and enter the font name against the Font (PDF) field.
