Where do language files locate?

TomatoCMS is modularized. Each module consists of many widgets which are located in the ModuleDirectory/widgets directory. Language file for module is located in app/modules/Name_Of_Module/languages directory, meanwhile, language file for widget is located in the same directory as widget.

Following figure illustrates where the languages files of news module are.

Languages directory of module

In above figure, (1) indicates the path and (2) indicates the list of available language files for news module.

Structure of language file

Language file have to be named as lang.xx_YY.ini where XX is language code and YY is country code. You can find the list of language codes here and country codes here.

So, if you want to create a French language pack for news module, you have to create file named lang.fr_FR.ini in app/modules/news/languages directory.

The language file is simple text file grouped by some sections. Don't care about the section at this time, I will explain it later. Each line below the section has the format of key=value:

[about]
about_news_description = "Manage articles"
dashboard_list_articles = "List of most recently articles"
dashboard_add_article = "Write new article"
dashboard_list_hot_articles = "Hot articles"
permisson_article = "Manage articles"
permisson_article_activate = "Activate article"
permisson_article_add = "Add new article"
permisson_article_delete = "Delete article"
permisson_article_edit = "Edit article"
permisson_article_hot = "Manage hot articles"
permisson_article_list = "View the list of articles"

[article]
article_category_latest_articles = "Latest articles"
article_category_previous_page = "Previous page"
article_category_posted_by = "Posted by %s at %s"
article_category_posted_in = "in %s"
article_category_next_page = "Next page"
article_category_read_more = "Read more"
article_details_posted_by = "Posted by %s at %s"

Don't edit the key, it is used to identify the language properties in source code. Now, you can edit the value manually.

Also, you have to keep the characters like %s or %d in the value, it will be replaced with values taken from the database or some dynamic things.

In order to create language files for widgets, performs similar steps.

For example, creating a French language for category widget from news module includes steps:

- Copy lang.en_US.ini file in the widget directory (app/modules/news/widgets/category),

- Paste it in this directory and rename to lang.fr_FR.ini,

- Update the value of language keys in lang.fr_FR.ini file.

Creating new language file for widget

Applies new language

To apply or test new language, you have to do only one action: change the language setting in TomatoCMS configuration file.

Open app/config/app.ini file and change the value for lang setting to your language code, fr_FR, for example:

[web]
lang="fr_FR"

Is there a tool for creating/updating the language file in backend?

Yes. You don't have to create and edit file manually. TomatoCMS provides language editor that allows you to create and update language file easily.

In backend, go to Custom >> Language menu. This page shows all available languages for modules and its widgets.

List of available languages for modules and widgets

(1): Select module

(2): If you want to create language for widget, select the widget that belong to the module you have just selected. If you don't select the widget, this form will create language file for module.

(3): Enter the language code in format of xx_YY. In the above figure, fr_FR means that we are going to create French language pack for news module.

(4): Press Create button to jump to page that allows you to update language file.

(5): List of available languages for each widgets. Click on the language name to go to the updating language page.

You will be redirected to the updating language file like follow:

You can update language file in backend

(1): As I said earlier, the language file was grouped by one or more sections. You can click on the name of section to show or hide all language items that belong to the section.

This is one of reasons why we need section in language file. It is easy for developers to develop and maintain language file. (What happen if the language file consist of too many items? It is not easy for you to find an item, isn't it?)

(2): Click on value that associates with the key of language item to update its value. For canceling, press the Esc key.

(3): If you want to remove the item, press Remove link

(4): You can add new item to given section or create new section.

Does TomatoCMS support other formats of language file, XML, CSV for example?

No, at this version and maybe in the future, TomatoCMS does not support any fomats of language files like XML, CSV but ini.

TomatoCMS uses Zend_Translate component. Although Zend_Translate supports various formats including INI, XML, ... but we choose INI because of two reasons:

- The INI file is simple,

- And processing INI file is simpler and quicker than XML one. It makes our site run quicker.

I didn't see the effect on frontend although I made some changes on language file. What is wrong?

There is nothing wrong here

For improving performance of loading and processing language file, TomatoCMS caches language data if it detects the cache was enabled. In this case, you have to clear the cache.

Go to menu Custom >> Cache in backend:

Cache management

(1): The cache type you are using. In this case, our site caches data to files, so it uses Zend_Cache_Backend_File as backend caching.

(2): All language items was tagged Zend_Translate. You can click on tag label to show or hide all cached items which associates with the tag.

(3), (4): You can click on Delete link to delete all cached items of given tag or certain item.

(5): Click on Clear link if you want to empty the cache.

Conclusion

I though that the language editor should allows user to upload new language from local computer. It is useful if user downloaded language files from other site. This maybe comes in TomatoCMS 2.0.2 version.

Now, it is great if you translate TomatoCMS into your language. And there will have many TomatoCMS download versions that include certain language package. Lets us know if you are goting to do this.

Waiting for your translation!