Actions

Creating language packs for extensions in Joomla 2.5

From Joomla! Documentation

Revision as of 11:27, 3 March 2012 by Horus 68 (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Copyedit.png
This Article Needs Your Help

This article is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


Although Joomla 2.5 supports installing language files for the front end (site) or back end (admin), it has no dedicated way to install language files for extensions (components, plugins, modules) unless they are installed with the extension itself.

Fortunately, since Joomla 1.6, Joomla supports a powerful way to install an arbitrary set of files called a 'files' installation unit. (See Installation unit for an arbitrary set of files named 'files_test1').

Example Plugin Language Pack

Suppose you have a content plugin named 'alpha' that you want to create a new language pack for language zz-ZZ. Here is what your language pack files in the folder 'alpha_zz_zz_language_pack' might look like:

── alpha_zz_zz_language_pack
   ├── index.html
   ├── alpha_zz_zz_language_pack.xml
   ├── zz-ZZ.plg_content_alpha.ini
   ├── zz-ZZ.plg_content_alpha.sys.ini
   └── language
       ├── en-GB
       │   └── en-GB.files_alpha_zz_zz_language_pack.sys.ini
       └── zz-ZZ
           └── zz-ZZ.files_alpha_zz_zz_language_pack.sys.ini

where the file 'alpha_zz_zz_language_pack.xml' is the installation manifest file.

The manifest file would look something like this:

   <?xml version="1.0" encoding="utf-8"?>
   <extension version="2.5" type="file" method="upgrade">
     <name>alpha_zz_zz_language_pack</name>
     <version>1.0.0</version>
     <creationDate></creationDate>
     <author></author>
     <authorEmail></authorEmail>
     <authorUrl></authorUrl>
     <copyright>Copyright (C) 2011 ???. All rights reserved.</copyright>
     <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
     <description>ALPHA_ZZ_ZZ_LANGUAGE_PACK</description>
     <fileset>
       <files target="plugins/content/alpha/language/zz-ZZ">
         <filename>index.html</filename>
         <filename>zz-ZZ.plg_content_alpha.ini</filename>
         <filename>zz-ZZ.plg_content_alpha.sys.ini</filename>
       </files>
       <files folder="language/en-GB" target="language/en-GB">
         <filename>en-GB.files_alpha_zz_zz_language_pack.sys.ini</filename>
       </files>
       <files folder="language/zz-ZZ" target="language/zz-ZZ">
         <filename>zz-ZZ.files_alpha_zz_zz_language_pack.sys.ini</filename>
       </files>
     </fileset>
   <updateservers>
       <server type="collection" priority="1" name="zz-ZZ Language Updates">http://update.zzZZ.com/translationlist.xml</server>
   </updateservers>
   </extension>

Special note: This example includes also the update servers statment for languages updates using the discovery feature on Joomla Extensions manager


A few notes and warnings:

  • Once this installed, the pseudo-language pack will be listed in the Extension manager (not the language manager).
  • This approach installs the plugin language files into the correct location inside the plugin folder. This is the new approach for the location of extension language files in Joomla 1.6+.
  • The language files 'zz-ZZ.files_alpha_zz_zz_language_pack.sys.ini' (and its English counterpart) will be put into the top-level (site) language/ folder. They are only needed for displaying the name of this pseudo-language pack in the Extension manager.
  • The English version of the language pack file was included for convenience since English is often a second language for many sites.
  • All of the language files could technically have been in the top directory, but this example shows how to set up files in folders in the language pack folder using the 'folder=' attribute in the XML <files> tag as shown. Also, putting them in folders as shown ensures that the installer can find them during installation to use them to display the name of the language pack as part of the installation confirmation.

The file 'zz-ZZ.files_alpha_zz_zz_language_pack.sys.ini' might have only one line like this:

FILES_ALPHA_ZZ_ZZ_LANGUAGE_PACK=="Plugin Alpha zz-ZZ Language Pack"
  • The English version would have similar contents.
  • Note that both the XML items 'name' and 'description' use the same term here (ALPHA_ZZ_ZZ_LANGUAGE_PACK) for convenience. If you use different terms, be sure to add separate entries for each in the file 'zz-ZZ.files_alpha_zz_zz_language_pack.sys.ini'.
  • Note that the name of the language key (to the left of the equals sign) must be identical to the name of the manifest file prefixed with 'files_' in order for the extension manager to find it.

Creating a language pack for several extensions in one file

This same a approach can be used to create a single language pack for several extensions at once. Just create a language pack as shown above for a plugin and add additional <files> sections for each component, plugin, and module. An additional benefit is that language-specific versions of the help file can be installed in their correct locations as well.

For example suppose we have an extension composed a plugin 'alpha' and a component 'beta'. To create the zz-ZZ language pack, set up files in the following directory structure:

── extension_zz_zz_language_pack
   ├── extension_zz_zz_language_pack.xml
   ├── com_beta
   │   ├── admin
   │   │   ├── help
   │   │   │   └── zz-ZZ
   │   │   │       ├── help.css
   │   │   │       ├── help.html
   │   │   │       └── index.html
   │   │   ├── index.html
   │   │   ├── zz-ZZ.com_beta.ini
   │   │   └── zz-ZZ.com_beta.sys.ini
   │   └── site
   │       ├── index.html
   │       └── zz-ZZ.com_beta.ini
   ├── plg_alpha
   │   ├── index.html
   │   ├── zz-ZZ.plg_content_alpha.ini
   │   └── zz-ZZ.plg_content_alpha.sys.ini
   └── language
       ├── en-GB
       │   └── en-GB.files_extension_zz_zz_language_pack.sys.ini
       └── zz-ZZ
           └── zz-ZZ.files_extension_zz_zz_language_pack.sys.ini

The corresponding manifest file, extension_zz_zz_language_pack.xml, would like something like this:

 <?xml version="1.0" encoding="utf-8"?>
 <extension version="2.5" type="file" method="upgrade">
     <name>extension_zz_zz_language_pack</name>
     <version>1.0.0</version>
     <creationDate></creationDate>
     <author></author>
     <authorEmail></authorEmail>
     <authorUrl></authorUrl>
     <copyright>Copyright (C) 2011 ???. All rights reserved.</copyright>
     <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
     <description>EXTENSION_ZZ_ZZ_LANGUAGE_PACK</description>
     <fileset>
         <files folder="com_beta/admin" target="administrator/components/com_beta/language/zz-ZZ">
             <filename>index.html</filename>
             <filename>zz-ZZ.com_beta.ini</filename>
             <filename>zz-ZZ.com_beta.sys.ini</filename>
         </files>
         <files folder="com_beta/admin/help/" target="administrator/components/com_beta/help">
             <folder>zz-ZZ</folder>
         </files>
         <files folder="com_beta/site" target="components/com_beta/language/zz-ZZ">
             <filename>index.html</filename>
             <filename>zz-ZZ.com_beta.ini</filename>
         </files>
         <files folder="plg_alpha" target="plugins/content/alpha/language/zz-ZZ">
             <filename>index.html</filename>
             <filename>zz-ZZ.plg_content_alpha.ini</filename>
             <filename>zz-ZZ.plg_content_alpha.sys.ini</filename>
         </files>
         <files folder="language/en-GB" target="language/en-GB">
             <filename>en-GB.files_extension_zz_zz_language_pack.sys.ini</filename>
         </files>
         <files folder="language/zz-ZZ" target="language/zz-ZZ">
             <filename>zz-ZZ.files_extension_zz_zz_language_pack.sys.ini</filename>
         </files>
     </fileset>
 </extension>

Note that we have created several different <files> sections for the admin language files, the admin help files, the site language files, the plugin language files, and the language files for the language pack itself.