Difference between revisions of "International Enhancements for Version 1.6"

From Joomla! Documentation

 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{RightTOC}}
+
Language and International Enhancements for Joomla 1.6, 1.7, 2.5, 3.x
Language and International Enhancements for Version 1.6
 
  
===3-Letter Language Prefixes for Installation===
+
==3-Letter Language Prefixes for Installation==
  
 
In version 1.5, we are limited to language prefixes of 2 letters at installation time. i.e fr-FR and not fra-FR. In all other areas of Joomla!, we can use 3-letter language prefixes. Many languages in the world can't be accomodated with a 2 letters prefix. ISO gives each langage a prefix. For example "ast" for Asturian (Spain), "sla" for Montenegrian (Montenegro) etc. See http://www.loc.gov/standards/iso639-2/php/code_list.php
 
In version 1.5, we are limited to language prefixes of 2 letters at installation time. i.e fr-FR and not fra-FR. In all other areas of Joomla!, we can use 3-letter language prefixes. Many languages in the world can't be accomodated with a 2 letters prefix. ISO gives each langage a prefix. For example "ast" for Asturian (Spain), "sla" for Montenegrian (Montenegro) etc. See http://www.loc.gov/standards/iso639-2/php/code_list.php
Line 12: Line 11:
 
References:
 
References:
  
* http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=19270
+
* [[jtracker:19270|Joomla! Tracker: [#19270] letters iso code language at installation time]]
  
 
The issue is not present when a user installs a customised distribution of Joomla as the installation language can be defined in the localise.xml file.
 
The issue is not present when a user installs a customised distribution of Joomla as the installation language can be defined in the localise.xml file.
  
=== Default Latin Transliteration ===
+
== Default Latin Transliteration ==
  
 
Transliteration is used in Joomla! to automatically create or modify non-compliant aliases into ASCII strings. These aliases are used for creating SEF URLs. I.e the title of an article or menu item can be "Émergé", the auto alias will transliterate it into "emerge"
 
Transliteration is used in Joomla! to automatically create or modify non-compliant aliases into ASCII strings. These aliases are used for creating SEF URLs. I.e the title of an article or menu item can be "Émergé", the auto alias will transliterate it into "emerge"
Line 23: Line 22:
  
 
In 1.6 has been added a table to help take care of most Latin languages.
 
In 1.6 has been added a table to help take care of most Latin languages.
 
  
 
'''Note:''' As in 1.5, when non latin glyphs are entered in the Title field, alias field is left empty and Unicode slugs are not implemented (see below), the alias field will automatically be filled with the present date)
 
'''Note:''' As in 1.5, when non latin glyphs are entered in the Title field, alias field is left empty and Unicode slugs are not implemented (see below), the alias field will automatically be filled with the present date)
  
===Custom Transliteration Support===
+
==Custom Transliteration Support==
  
 
For people who still want to use ASCII SEF but are not using a Latin language(Cyrillic, Greek,...) or with specific usage (some weird math glyphs, etc.) we have added the ability to override the default Latin transliteration by adding some code in a specific file called xx-XX.localise.php (use correct lang tag) in the core language pack for their language.
 
For people who still want to use ASCII SEF but are not using a Latin language(Cyrillic, Greek,...) or with specific usage (some weird math glyphs, etc.) we have added the ability to override the default Latin transliteration by adding some code in a specific file called xx-XX.localise.php (use correct lang tag) in the core language pack for their language.
Line 35: Line 33:
 
For example ω will be transliterated into an "o", etc.
 
For example ω will be transliterated into an "o", etc.
  
Concerning the xx-XX.override.php see: http://docs.joomla.org/Tutorial:Making_a_Language_Pack_for_Version_1.6
+
Concerning the xx-XX.override.php see [[Making a Language Pack for Joomla 1.6]].
  
 
All usage of this file is explained there in details.
 
All usage of this file is explained there in details.
  
===Unicode URLs===
+
==Unicode URLs==
  
 
Opposed to transliteration, one may now use natively in 1.6 Unicode urls. This parameter is defined in Global Configuration.
 
Opposed to transliteration, one may now use natively in 1.6 Unicode urls. This parameter is defined in Global Configuration.
 
This way of making aliases does not transliterate, it displays the utf8 glyphs instead of ascii.
 
This way of making aliases does not transliterate, it displays the utf8 glyphs instead of ascii.
It uses Percent Encodings to display correctly ( http://en.wikipedia.org/wiki/Percent-encoding ).
+
It uses Percent Encodings to display correctly ([[wikipedia:Percent-encoding]]).
  
 
Wikipedia demonstrates this in Persian:
 
Wikipedia demonstrates this in Persian:
Line 53: Line 51:
 
Google has no problem searching or referencing such links.
 
Google has no problem searching or referencing such links.
  
===Language String Overrides===
+
==Language String Overrides==
  
If you wish to change an existing value for a string present in Joomla! core or for a specific extension, the only solution in version 1.5 is to edit the ini file concerned and change the value of the string.
+
If you wish to change an existing value for a string present in the Joomla! core or for a specific extension, the only solution in version 1.5 was to edit the ''.ini'' file concerned and change the value of the string.
  
When updating Core, the extension or a translated ini file, your local changes can be overwritten if there are updates to the edited language file.
+
When updating the Core, the extension or a translated ''.ini'' file, your local changes can be overwritten if there are updates to the edited language file.
  
The new xx-XX.override.ini file has been created to avoid this issue. Instead of changing the original file, one can add in a file tagged to the language chosen (en-GB.override.ini for example) any key already existing somewhere among all ini files and a specific value.
+
The new ''xx-XX.override.ini'' file has been created to avoid this issue. Instead of changing the original file, one can add any key already existing somewhere among all ''.ini'' files and a specific value to a file named for the language chosen (''en-GB.override.ini'', for example).
  
The file has to be placed in administrator/languages/overrides/ or languages/overrides/ for frontend.
+
The file has to be '''administrator/language/overrides/en-GB.override.ini''' for the backend or '''language/overrides/en-GB.override.ini''' for the frontend.
  
For example, if you add the following value to the override.ini file:
+
For example, if you add the following key=value to the ''en-GB.override.ini'' file:
  
<code>JSAVE="Save now!"</code>, then this will replace the <code>JSAVE="Save"</code> throughout your site.
+
<code>JSAVE="Save now!"</code>, it will replace the <code>JSAVE="Save"</code> throughout your site.
  
This file will not be uninstalled or overwritten when updating. Since the override file loads last, ALL keys present in your Joomla can be overriden.
+
This file will not be uninstalled or overwritten when updating. Since the override file loads last, '''all''' keys present in your Joomla can be overriden.
  
===Language Folder For Extensions ===
+
==Language Folder For Extensions ==
  
 
In version 1.6, language files can be added to a language folder under the extension folder. For example, <code>mod_mymodule/language/en-gb/en-gb.mod_mymodule.ini</code>.
 
In version 1.6, language files can be added to a language folder under the extension folder. For example, <code>mod_mymodule/language/en-gb/en-gb.mod_mymodule.ini</code>.
Line 75: Line 73:
 
Extension developers can choose this solution instead of adding the language files inside the core folders. This does not prevent adding translation of these files in the main core folder. Users have still to beware when uninstalling a language, since this will delete all ini files in the core language folders, included extension-related ones.
 
Extension developers can choose this solution instead of adding the language files inside the core folders. This does not prevent adding translation of these files in the main core folder. Users have still to beware when uninstalling a language, since this will delete all ini files in the core language folders, included extension-related ones.
  
===The new .sys.ini===
+
==The new .sys.ini==
 
The .sys.ini language files are used for extension description translations on the install and update screens. These files are used so that descriptions of all extensions in the system can be loaded at once. This avoids the overhead of loading and parsing full language files for every installed extension. If you only need the description or name of an extension, it is preferable to load the .sys.ini file instead of the .ini file.
 
The .sys.ini language files are used for extension description translations on the install and update screens. These files are used so that descriptions of all extensions in the system can be loaded at once. This avoids the overhead of loading and parsing full language files for every installed extension. If you only need the description or name of an extension, it is preferable to load the .sys.ini file instead of the .ini file.
  
Line 81: Line 79:
  
 
As the 3pd can now include specific script at install time, the sys.ini is also used in case these scripts contain language keys.
 
As the 3pd can now include specific script at install time, the sys.ini is also used in case these scripts contain language keys.
 +
 +
The xml description in the sys.ini file is used at install time to display a message to specify the result of the install. This will work ONLY when the extension contains its own language folder. Example: language/xx-XX/xx-XX.nameofextension.sys.ini file
 +
 +
Look at the plugins/content/example/example.xml for details.
  
 
* '''!!''' All extensions should have a xx-XX.nameofextension.sys.ini file
 
* '''!!''' All extensions should have a xx-XX.nameofextension.sys.ini file
  
=== Langswitcher / Languagefilter ===
+
== Langswitcher / Languagefilter ==
  
 
This is a simple multilingual solution provided by one module and one plugin. See the tutorial [[Language_Switcher_Tutorial_for_Joomla_1.6]].
 
This is a simple multilingual solution provided by one module and one plugin. See the tutorial [[Language_Switcher_Tutorial_for_Joomla_1.6]].
  
===Pluralization Support for Translation Files===
+
==Pluralization Support for Translation Files==
  
 
1.6 uses a new function JText::plural() for usual ones.
 
1.6 uses a new function JText::plural() for usual ones.
Line 109: Line 111:
 
Concerning extremely customised languages where the value not only changes for zero, 1 and >1 but also for 5 for example (Russian) and depending of context, this is done in the same file xx-XX.localise.php stated above for transliteration.
 
Concerning extremely customised languages where the value not only changes for zero, 1 and >1 but also for 5 for example (Russian) and depending of context, this is done in the same file xx-XX.localise.php stated above for transliteration.
  
See http://docs.joomla.org/Tutorial:Making_a_Language_Pack_for_Version_1.6
+
See [[Making a Language Pack for Joomla 1.6]]
  
===Support for Non-Gregorian Calendars===
+
==Support for Non-Gregorian Calendars==
  
 
In the display of the date in front and back-end calendar fields, we need to be able to override the Javascript files used to render the dates. In version 1.6, we can now do that by installing custom Javascript in the media folder. That means that in version 1.6 Persian or other distributions no longer need to be hacked to get local calendar display and that these sites can be truly multi-language and permit switching and get the right calendar for the language concerned. This is done in the same file xx-XX.localise.php stated above for transliteration.
 
In the display of the date in front and back-end calendar fields, we need to be able to override the Javascript files used to render the dates. In version 1.6, we can now do that by installing custom Javascript in the media folder. That means that in version 1.6 Persian or other distributions no longer need to be hacked to get local calendar display and that these sites can be truly multi-language and permit switching and get the right calendar for the language concerned. This is done in the same file xx-XX.localise.php stated above for transliteration.
Line 117: Line 119:
 
This needs to be done this way because MySQL accepts only Gregorian dates, thus the need to calculate when saving and when loading for these languages.
 
This needs to be done this way because MySQL accepts only Gregorian dates, thus the need to calculate when saving and when loading for these languages.
  
See http://docs.joomla.org/Tutorial:Making_a_Language_Pack_for_Version_1.6
+
See [[Making a Language Pack for Joomla 1.6]]
 +
 
 +
==Calendar icon: new parameter==
 +
 
 +
This new meta parameter is set in the language xml file in each language pack.
 +
 
 +
<source lang="xml">
 +
<firstDay>0</firstDay>
 +
</source>
 +
 
 +
means that Sunday is considered as the first day in the week.
 +
 
 +
For French or Italian it would be Monday
 +
 
 +
<source lang="xml">
 +
<firstDay>1</firstDay>
 +
</source>
 +
 
 +
See [[Making a Language Pack for Joomla 1.6]]
  
===New Search related parameters===
+
==New Search related parameters==
  
 
The xx-XX.override.php  is also used to define new parameters concerning search.
 
The xx-XX.override.php  is also used to define new parameters concerning search.
Line 131: Line 151:
 
*Define the number of characters displayed in the results.
 
*Define the number of characters displayed in the results.
  
See http://docs.joomla.org/Tutorial:Making_a_Language_Pack_for_Version_1.6
+
See [[Making a Language Pack for Joomla 1.6]]
  
===Plugins Language Files===
+
==Templates Need Only One Language File==
 
 
In 1.5 any front-end display created by some plugins could not load their lang file in front-end.
 
 
 
This forced some 3pd to code specially to get these strings loaded. In version 1.6, plugin language files that exist in the back-end are loaded when the plugin renders output in the front end, eliminating the need for special code by 3pds.
 
 
 
===Templates Need Only One Language File===
 
  
 
Front-end templates using custom strings in the front-end need to have a separate language file for front-end in 1.5.
 
Front-end templates using custom strings in the front-end need to have a separate language file for front-end in 1.5.
  
 
In 1.6 we need only one file which is loaded in both the front and back ends. This ini file will now load custom template override strings as well.
 
In 1.6 we need only one file which is loaded in both the front and back ends. This ini file will now load custom template override strings as well.
 
  
 
<noinclude>[[Category:Joomla! 1.6]] [[Category:Languages]]</noinclude>
 
<noinclude>[[Category:Joomla! 1.6]] [[Category:Languages]]</noinclude>

Latest revision as of 04:50, 19 November 2014

Language and International Enhancements for Joomla 1.6, 1.7, 2.5, 3.x

3-Letter Language Prefixes for Installation[edit]

In version 1.5, we are limited to language prefixes of 2 letters at installation time. i.e fr-FR and not fra-FR. In all other areas of Joomla!, we can use 3-letter language prefixes. Many languages in the world can't be accomodated with a 2 letters prefix. ISO gives each langage a prefix. For example "ast" for Asturian (Spain), "sla" for Montenegrian (Montenegro) etc. See http://www.loc.gov/standards/iso639-2/php/code_list.php

Joomla tries to propose a specific language for installing depending on the browser's settings. Let's say a browser is set to use Slovenian as preferred language (sl). If, among the installation languages proposed by Joomla, we have a 3 letters ISO code language which tag starts by "sl" - the prefix- (for example for Montenegrin sla-ME) and IF the sl-SI Slovenian language pack is not present among J! languages, then a Slovenian would be presented with a Montenegrian first install screen.

No browsers as of today include 3-letters ISO languages. The only solution to prevent this is to default all 3 letters code Joomla! languages to English in the first install screen. At that point, you can choose the correct language for installation.

References:

The issue is not present when a user installs a customised distribution of Joomla as the installation language can be defined in the localise.xml file.

Default Latin Transliteration[edit]

Transliteration is used in Joomla! to automatically create or modify non-compliant aliases into ASCII strings. These aliases are used for creating SEF URLs. I.e the title of an article or menu item can be "Émergé", the auto alias will transliterate it into "emerge"

In 1.5, this transliteration would not know how to manage for Latin supplement, Extended A letters used in some central European countries and people had to modify manually their aliases when created automatically.

In 1.6 has been added a table to help take care of most Latin languages.

Note: As in 1.5, when non latin glyphs are entered in the Title field, alias field is left empty and Unicode slugs are not implemented (see below), the alias field will automatically be filled with the present date)

Custom Transliteration Support[edit]

For people who still want to use ASCII SEF but are not using a Latin language(Cyrillic, Greek,...) or with specific usage (some weird math glyphs, etc.) we have added the ability to override the default Latin transliteration by adding some code in a specific file called xx-XX.localise.php (use correct lang tag) in the core language pack for their language.

We have such a file and a sample table for Latin 1, Latin supplement , extended A, Cyrillic, Greek in the temporary xx-XX site language folder in 1.6 trunk (this language will be taken off when 1.6 reaches RC). It adds a table where all the said glyphs are transliterated to their ASCII counterparts, charge to the Translation Team providing the packs to make sure this transliteration is correct.

For example ω will be transliterated into an "o", etc.

Concerning the xx-XX.override.php see Making a Language Pack for Joomla 1.6.

All usage of this file is explained there in details.

Unicode URLs[edit]

Opposed to transliteration, one may now use natively in 1.6 Unicode urls. This parameter is defined in Global Configuration. This way of making aliases does not transliterate, it displays the utf8 glyphs instead of ascii. It uses Percent Encodings to display correctly (wikipedia:Percent-encoding).

Wikipedia demonstrates this in Persian: http://ps.wikipedia.org/wiki/فارسي is in fact: http://ps.wikipedia.org/wiki/%D9%81%D8%A7%D8%B1%D8%B3%D9%8A

Browsers behave differently when copying such urls. Firefox will copy the unicode format while Opera will get the original glyphs. Google has no problem searching or referencing such links.

Language String Overrides[edit]

If you wish to change an existing value for a string present in the Joomla! core or for a specific extension, the only solution in version 1.5 was to edit the .ini file concerned and change the value of the string.

When updating the Core, the extension or a translated .ini file, your local changes can be overwritten if there are updates to the edited language file.

The new xx-XX.override.ini file has been created to avoid this issue. Instead of changing the original file, one can add any key already existing somewhere among all .ini files and a specific value to a file named for the language chosen (en-GB.override.ini, for example).

The file has to be administrator/language/overrides/en-GB.override.ini for the backend or language/overrides/en-GB.override.ini for the frontend.

For example, if you add the following key=value to the en-GB.override.ini file:

JSAVE="Save now!", it will replace the JSAVE="Save" throughout your site.

This file will not be uninstalled or overwritten when updating. Since the override file loads last, all keys present in your Joomla can be overriden.

Language Folder For Extensions[edit]

In version 1.6, language files can be added to a language folder under the extension folder. For example, mod_mymodule/language/en-gb/en-gb.mod_mymodule.ini.

Extension developers can choose this solution instead of adding the language files inside the core folders. This does not prevent adding translation of these files in the main core folder. Users have still to beware when uninstalling a language, since this will delete all ini files in the core language folders, included extension-related ones.

The new .sys.ini[edit]

The .sys.ini language files are used for extension description translations on the install and update screens. These files are used so that descriptions of all extensions in the system can be loaded at once. This avoids the overhead of loading and parsing full language files for every installed extension. If you only need the description or name of an extension, it is preferable to load the .sys.ini file instead of the .ini file.

The new sys.ini file replaces the .menu.ini in 1.5 and provides translation in some Managers.

As the 3pd can now include specific script at install time, the sys.ini is also used in case these scripts contain language keys.

The xml description in the sys.ini file is used at install time to display a message to specify the result of the install. This will work ONLY when the extension contains its own language folder. Example: language/xx-XX/xx-XX.nameofextension.sys.ini file

Look at the plugins/content/example/example.xml for details.

  • !! All extensions should have a xx-XX.nameofextension.sys.ini file

Langswitcher / Languagefilter[edit]

This is a simple multilingual solution provided by one module and one plugin. See the tutorial Language_Switcher_Tutorial_for_Joomla_1.6.

Pluralization Support for Translation Files[edit]

1.6 uses a new function JText::plural() for usual ones.

Code example:

$this->setMessage(JText::plural('COM_USERS_N_USERS_ACTIVATED', count($ids)));

will use the following ini strings:

COM_USERS_N_USERS_ACTIVATED="%s Users successfully activated"
COM_USERS_N_USERS_ACTIVATED_1="User successfully activated"

To which could be added for languages where the equivalent to the word "Users" is different for 0 and for multiple:

COM_USERS_N_USERS_ACTIVATED_0="0 (or No) users activated"

etc.

Concerning extremely customised languages where the value not only changes for zero, 1 and >1 but also for 5 for example (Russian) and depending of context, this is done in the same file xx-XX.localise.php stated above for transliteration.

See Making a Language Pack for Joomla 1.6

Support for Non-Gregorian Calendars[edit]

In the display of the date in front and back-end calendar fields, we need to be able to override the Javascript files used to render the dates. In version 1.6, we can now do that by installing custom Javascript in the media folder. That means that in version 1.6 Persian or other distributions no longer need to be hacked to get local calendar display and that these sites can be truly multi-language and permit switching and get the right calendar for the language concerned. This is done in the same file xx-XX.localise.php stated above for transliteration.

This needs to be done this way because MySQL accepts only Gregorian dates, thus the need to calculate when saving and when loading for these languages.

See Making a Language Pack for Joomla 1.6

Calendar icon: new parameter[edit]

This new meta parameter is set in the language xml file in each language pack.

<firstDay>0</firstDay>

means that Sunday is considered as the first day in the week.

For French or Italian it would be Monday

<firstDay>1</firstDay>

See Making a Language Pack for Joomla 1.6

New Search related parameters[edit]

The xx-XX.override.php is also used to define new parameters concerning search.

It replaces the xx-XX.ignore.php in 1.5 and includes new functionalities:

  • Define the words to not search for (as the ignore.php)
  • Define a lower limit and upper limit of characters to search for, in order to accommodate 2 bytes languages as Chinese.
  • Define the number of characters displayed in the results.

See Making a Language Pack for Joomla 1.6

Templates Need Only One Language File[edit]

Front-end templates using custom strings in the front-end need to have a separate language file for front-end in 1.5.

In 1.6 we need only one file which is loaded in both the front and back ends. This ini file will now load custom template override strings as well.