Actions

J1.5

Difference between revisions of "Language Guidelines for 3rd Party Extensions"

From Joomla! Documentation

(− 5 categories; +Category:Archived version Joomla! 1.5 using HotCat)
 
(9 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 +
{{RightTOC}}
 
The purpose of this document is to give some guidelines for developers for their 3rd party Joomla! 1.5 extension, so that users can easier adapt extensions for use in their local language. '''These guidelines are not rules''' which would limit their freedom in development and distribution. But extensions based on these guidelines will be more flexible and easier to translate, which might have a positive influence on their use and popularity.  
 
The purpose of this document is to give some guidelines for developers for their 3rd party Joomla! 1.5 extension, so that users can easier adapt extensions for use in their local language. '''These guidelines are not rules''' which would limit their freedom in development and distribution. But extensions based on these guidelines will be more flexible and easier to translate, which might have a positive influence on their use and popularity.  
  
Line 4: Line 5:
 
A module (e.g. mod_somemodule) with the following hard coded Dutch language text in the XML installation (and configuration) file,  
 
A module (e.g. mod_somemodule) with the following hard coded Dutch language text in the XML installation (and configuration) file,  
 
needs to be fully analyzed and rewritten for any other language.
 
needs to be fully analyzed and rewritten for any other language.
<source lang="ini">
+
<source lang="xml">
 
<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M"  
 
<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M"  
 
  label="Datum / Tijd formaat" description="Gebruik de PHP strftime datum en tijd opmaak." />
 
  label="Datum / Tijd formaat" description="Gebruik de PHP strftime datum en tijd opmaak." />
Line 13: Line 14:
 
== Use language labels instead ==
 
== Use language labels instead ==
 
The same mod_somemodule.xml installer file but now with language labels is much easier to translate!
 
The same mod_somemodule.xml installer file but now with language labels is much easier to translate!
<source lang="ini">
+
<source lang="xml">
 
<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M"  
 
<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M"  
 
  label="DATUMTIJDFORMAAT" description="DATUMTIJDFORMAATBESCHR" />
 
  label="DATUMTIJDFORMAAT" description="DATUMTIJDFORMAATBESCHR" />
Line 30: Line 31:
 
== Use English language labels ==
 
== Use English language labels ==
 
The previous example with language labels and an external language file is easier to translate. However Non-Dutch users will have much difficulties in translating the language file. Please use English language labels instead!
 
The previous example with language labels and an external language file is easier to translate. However Non-Dutch users will have much difficulties in translating the language file. Please use English language labels instead!
<source lang="ini">
+
<source lang="xml">
 
<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M"  
 
<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M"  
 
  label="DATETIMEFORMAT" description="DATETIMEFORMATDESCR" />
 
  label="DATETIMEFORMAT" description="DATETIMEFORMATDESCR" />
Line 55: Line 56:
 
POSTTEXTDESCR = Any text that should be placed after the date.
 
POSTTEXTDESCR = Any text that should be placed after the date.
 
</source>
 
</source>
 +
 +
Another reason to provide an English language file is to help translators using the [http://joomlacode.org/gf/project/trans_mngr/frs/ Translation Manager Component] to create the file in other languages.
 +
The Translation Manager Component proposes the basic en-GB set as a reference when creating/editing these files.
  
 
== PHP strftime ==
 
== PHP strftime ==
Line 60: Line 64:
  
 
== Use UTF8 ==
 
== Use UTF8 ==
All .ini language files need to be saved as UTF-8 for the proper display of characters which are not in the ASCII range [a..z] and [A..Z].
+
All .ini language files need to be saved as UTF-8 no BOM for the proper display of characters which are not in the ASCII range [a..z] and [A..Z].
  
 
es-ES.mod_somemodule.ini
 
es-ES.mod_somemodule.ini
Line 73: Line 77:
 
== Group logical entities in translation file ==
 
== Group logical entities in translation file ==
 
Large translation files are difficult to read. Try to group logical entities together, and use # comment lines (start with "#") to describe the logical entity. A good example is the Joomla core translation file '''/language/en-GB/en-GB.ini'''. Date format, Months, Days of the Week, Time Zones, Mailer Codes are all grouped together and those logical entities start with a comment line.
 
Large translation files are difficult to read. Try to group logical entities together, and use # comment lines (start with "#") to describe the logical entity. A good example is the Joomla core translation file '''/language/en-GB/en-GB.ini'''. Date format, Months, Days of the Week, Time Zones, Mailer Codes are all grouped together and those logical entities start with a comment line.
 +
 +
Another possibility is the usage of '''brackets''' like [here is the group for advanced parameters].
  
 
== Translation File Version Control ==
 
== Translation File Version Control ==
Line 92: Line 98:
 
* [[Location of template language definition files]]
 
* [[Location of template language definition files]]
 
* [[Formatted fields in language translation strings]]
 
* [[Formatted fields in language translation strings]]
 +
<noinclude>
 +
[[Category:Archived version Joomla! 1.5]]
 +
</noinclude>

Latest revision as of 16:11, 6 June 2013

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

Contents

The purpose of this document is to give some guidelines for developers for their 3rd party Joomla! 1.5 extension, so that users can easier adapt extensions for use in their local language. These guidelines are not rules which would limit their freedom in development and distribution. But extensions based on these guidelines will be more flexible and easier to translate, which might have a positive influence on their use and popularity.

Do NOT use hard coded language text

A module (e.g. mod_somemodule) with the following hard coded Dutch language text in the XML installation (and configuration) file, needs to be fully analyzed and rewritten for any other language.

<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M" 
 label="Datum / Tijd formaat" description="Gebruik de PHP strftime datum en tijd opmaak." />
<param name="posttext" type="text" default="" 
 label="Tekst achter datum" description="Eventuele tekst die achter de datum wordt getoond." />

Use language labels instead

The same mod_somemodule.xml installer file but now with language labels is much easier to translate!

<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M" 
 label="DATUMTIJDFORMAAT" description="DATUMTIJDFORMAATBESCHR" />
<param name="posttext" type="text" default="" 
 label="TEKSTACHTER" description="TEKSTACHTERBESCHR" />

Only the nl-NL.mod_somemodule.ini language file needs to be translated to get the module working in any other language:

DATUMTIJDFORMAAT = Datum / Tijd formaat
DATUMTIJDFORMAATBESCHR = Gebruik de PHP strftime datum en tijd opmaak.
TEKSTACHTER = Tekst achter datum
TEKSTACHTERBESCHR = Eventuele tekst die achter de datum wordt getoond.

Use English language labels

The previous example with language labels and an external language file is easier to translate. However Non-Dutch users will have much difficulties in translating the language file. Please use English language labels instead!

<param name="dateformat" type="text" default="%A %d %B %Y, %H:%M" 
 label="DATETIMEFORMAT" description="DATETIMEFORMATDESCR" />
<param name="posttext" type="text" default="" 
 label="TEXTAFTER" description="POSTTEXTDESCR" />

And the same English labels with Dutch translation in nl-NL.mod_somemodule.ini

DATETIMEFORMAT = Datum / Tijd formaat
DATETIMEFORMATDESCR = Gebruik de PHP strftime datum en tijd opmaak.
TEXTAFTER = Tekst achter datum
POSTTEXTDESCR = Eventuele tekst die achter de datum wordt getoond.

Include an English language file

Again, the above example is easier to translate because of the English labels. But again, not everyone can read and translate the Dutch translation. Most people can read English, so include at least an English language file. Translating English to some other language is easier for most people.

en-GB.mod_somemodule.ini

DATETIMEFORMAT = Date/Time format
DATETIMEFORMATDESCR = Use the PHP strftime formatting.
TEXTAFTER = Text after date
POSTTEXTDESCR = Any text that should be placed after the date.

Another reason to provide an English language file is to help translators using the Translation Manager Component to create the file in other languages. The Translation Manager Component proposes the basic en-GB set as a reference when creating/editing these files.

PHP strftime

Countries have different date and time formats. Please use the PHP strftime function for dates and times in your extension. That way the local date/time format will be used automatically, because it's based on the local format.

Use UTF8

All .ini language files need to be saved as UTF-8 no BOM for the proper display of characters which are not in the ASCII range [a..z] and [A..Z].

es-ES.mod_somemodule.ini

DATETIMEFORMAT = Formato de fecha/tiempo
DATETIMEFORMATDESCR = Usan el PHP strftime formateo.
TEXTAFTER = Texto después de Fecha
POSTTEXTDESCR = Cualquier texto que debería ser colocado después de la fecha.

después is UTF-8 and will be displayed as después.

Group logical entities in translation file

Large translation files are difficult to read. Try to group logical entities together, and use # comment lines (start with "#") to describe the logical entity. A good example is the Joomla core translation file /language/en-GB/en-GB.ini. Date format, Months, Days of the Week, Time Zones, Mailer Codes are all grouped together and those logical entities start with a comment line.

Another possibility is the usage of brackets like [here is the group for advanced parameters].

Translation File Version Control

Keep in mind that your extensions might be used in a broad range of different languages. A new release of a new version of your extension might have changes in your default language file. If your extension has a large language files, then individual users might have difficulties to find the changes. Please make their lives easier and find a way to make translation easier. Some 3rd party extension developers put changed language labels on top, or bottom, of the language files which makes the changes easier to spot. Some added # comments (e.g. with version information) are also very welcome.

[Please suggest more workable solutions here]

Collect and distribute translations

Ask your users to send you any missing language translation files, and make those available for download at the same place as your extension. Creating new translations, while others have already done that, is a waste of time.

Conclusion

Make your extensions easy to translate with these guidelines. The result of easy translation able extensions is that more users can benefit from your hard work.

Other documentation

More information regarding the use of language files can be found at the following places: