A significant attempt has been made within UserSpice to replace every hardcoded string with a language token to allow for web-sites (or even users) who prefer a different language.

An overall site language is configured in admin_settings.php under General (the default is "english.php"). You can choose a different language that you have installed and the overall site language will automatically be changed.

On the roadmap for UserSpice we will implement per-user languages. This is not yet complete.

Changing some text or message to match your preference

Sometimes the way a message or a title is worded just doesn't work for your site and you would like to change that.

So perhaps the current wording on a form says "Mark for Deletion" and you prefer it to read "Select Items To Delete". You would go into core/language/english.php (or the language file you are using) and find the appropriate language token you wish to change. In this case it is this line:

  'MARK_TO_DELETE'                       => 'Mark for Deletion',

DO NOT MAKE THE CHANGE IN THIS core/language/x SCRIPT! If you do then your changes will be lost the next time you upgrade UserSpice. (This is a rule in all UserSpice - avoid making changes to any files found in the core/ directory or below it.

Instead create a new file in local/language/ making sure that you have chosen the correct directory and that the actual script name corresponds exactly to the language file you are wishing to alter from core/language (for instance, local/language/english.php. (If you have a different name in local/language/ than in core/language/ then it will not work.)

Place this content in that newly created script to make the change mentioned in our example:

$lang = array_merge($lang, array(
  //Sam said this worked better for our Xyz web-site
  'MARK_TO_DELETE'                       => 'Select Items To Delete',
));

The next time you load a page on your web-site you should see that your customized message now appears in place of the core message that you customized.

If you are changing more than 1 text string then simply add new entries to that list:

$lang = array_merge($lang, array(
  //Sam said this worked better for our Xyz web-site
  'MARK_TO_DELETE'                       => 'Select Items To Delete',
  'MARK_TO_CREATE'                       => 'Select Items to Create',
  'MARK_TO_ADD'                          => 'Select Items to Add',
));

Using lang() in your own coding and web development

As you are coding your own pages it is recommended that you use lang() instead of hard-coded strings whenever possible. Even though your site may be mono-lingual now it is wise to plan for the future in this globalized world.

Simply create a language file (preferably language/english.php) under your custom web-development directory established during installation. (If you did not set this up then you will need to edit your local/config.php and set up the alt_dev_path configuration key.) So if alt_dev_path in local/config.php points to myapp/ then you would create your language file in myapp/language/english.php (or another language name). Set it up in the same way that changes are made in local/language/ but simply using this alternate directory.

You can also use the language files in local/language for your own 3rd-party development and they will not be over-written during upgrades. But it may be confusing, later on, to figure out which entries in local/language are for UserSpice customizations and which are there for your own 3rd-party development. For this reason it is preferable to set it up in the alt_dev_path directory.

Translating into a new language

If you would like to translate UserSpice into a new language, simply copy core/language/english.php to a script-name of your choice (presumably naming it according to the name of the language you are translating) under local/language and then go through that new script, translating the RIGHT SIDE (not the tokens on the left side!) into your new language.

Thus if I were translating into the Albanian language (shqip) I would copy english.php to shqip.php and then I would change the following lines:

$lang = array_merge($lang, array(
  //Generic labels
  'CHOOSE_FROM_LIST_BELOW'               => 'Choose from the list below',
  'READ_ONLY'                            => 'Read Only',
  'DELETE'                               => 'Delete',
  'SAVE_CHANGES'                         => 'Save Changes',

so that after translation they look like this:

$lang = array_merge($lang, array(
  //Generic labels
  'CHOOSE_FROM_LIST_BELOW'               => 'Zgjidhni nga lista me poshte',
  'READ_ONLY'                            => 'Vetem lexohet',
  'DELETE'                               => 'Fshije',
  'SAVE_CHANGES'                         => 'Ruani Ndryshimet',

PLEASE, after you have done a translation into a new language, share it with the UserSpice community.