One of the most frustrating things about Joomla is it’s lack of thorough documentation. Yeah, there’s an API… yeah there’s a Wiki… but it just seems like there are a lot of gaps and holes that don’t necessarily have to exist. Here’s a quick tutorial on how to implement languages in your component in Joomla! 1.5.
First off, lets talk about why this tutorial is important. Let’s say you’re creating a component to give site admins a way to easily create a special Links (yes, there’s already one for Joomla, it’s 2am, just go with me on this) section. On the back-end, you’ve got an “Add Link Category” page that takes admins to a nice form that lets them create a category for links in this component. So you’ve got text for “Name:” and “Description:” and maybe even “Category Image:” if they want to use an image with the text. You finish your component and release it, and someone in the Joomla community wants to make a Spanish version of your component. They would have to dig into your source code and basically re-write all of your inline html that you’ve written; essentially necessitating a while new release of your component in an “English version” and “Spanish version.”
Joomla has built-in ways to handle translating different languages that, if you, the developer, made habit from the beginning, would mean that Señor Spanish-speaker would simply need to edit one file, and that would change the text in your whole component to Spanish. You now could simply include this spanish language file with your component and now users could choose either an English or Spanish version of the TEXT of your component.
As a general rule, if you type ANY text in English that will be printed onto the screen, you should place that text in a language file. You will need a special language file for the admin area, as well as a separate file for the front-end if you are outputting text in English that You, the developer, are coding into your component.
For example, in Staff Master, I do not have a language file for the front end, because ALL text that is being printed out on the front-end is either stored in the database config area where an admin can change it depending on their locale, or it is entered and stored in the database through the WYSIWYG editor in the admin area, in which case the admin entering the data can type in whatever language they want and the output isn’t dependent on how I’ve coded the component. Let’s get started…
When you begin developing your component, create a file ( for English ) called
[code language=”html”]en-GB.com_
and leave it open as you code. If you plan on coding specific text to print out on the front end, you’ll need another file with exactly the same name. These files will be placed in two separate folders and Joomla will know where to put them and how to deal with them. In this tutorial we’re only going to focus on the back-end, but the same principles apply to both sides of your component.
So, now that we have the language file created, Joomla will automatically know to include this file without us needing to specify or include/require/jimport the file.
Using our example Link component from before, as we code the html output, instead of coding this:
[code language=”html”]
[/code]
we’re going to use this:
[code language=”php”]
[/code]
You’ll notice I used the JText class and called a generic _( ) function. This class and function tells Joomla to go look for an identifier key named LINK NAME and return its value from the administrator/language/en-GB/en-GB.com_
So, lets go into that file you already have created and already have open to save us time.
In en-GB.com_
[code language=”html”]NAME =Name[/code]
Anything before the equals sign is the “key” and anything after the equals sign is the “value.” If you typed in
[code language=”html”]NAME = Name[/code]
it will put a space before Name when it prints to the screen. So be mindful of the fact that Anything after the equals sign will be printed out up til the end of that line.
As far as the key names go, I used my own little naming scheme of TH_NAME if this value was supposed to be a table heading, or TD_NAME if it was supposed to simply be printed out in a table cell. I don’t think there’s any right or wrong way stated on how to do this, just as long as it makes sense to you and would make sense to anyone trying to modify your file.
Now that you’re using the language file and JText in your component, someone from the community can simply create a file called es.com_<component name>.ini , copy all of your text from your english file into the spanish file, and change the values:
[code language=”html”]NAME =Nombe[/code]
and now, if they have told Joomla to use Spanish language files, your component will now show “Nombre” where you had originally used “Name.”
Almost done… So now you have finished your component… you have a language file with a LOT of data in it and you’ve gone back and double checked and made sure that any English to be printed out is all in the language file and you’ve used JText::_( ‘KEY NAME’ ) for all of the keys.
Installation XML file. In your directory structure of the zipped version of your component, you’ll have an ‘admin’ and ‘site’ folder for the files that go in Joomla’s back-end and front-end respectively. For languages, we’ll make a separate folder called ‘language’ and inside of that folder we’ll create Another folder called ‘admin’ If you have a separate language file for the front end, you’ll also add a folder called ‘site’ under the ‘language’ folder, so ‘language’ would then also have an ‘admin’ and ‘site’ folder. Your en-GB.com_
In the XML file:
[code language=”xml”]
…
…
en-GB.com_
…
[/code]
These lines will tell Joomla to take the backend admin language file out of ‘language/admin’ and place it in ‘administrator/language/en-GB/’ on your server when the component is installed. That should do it! Please feel free to email me with questions or post comments and questions below.
-Haelix
0 Comments