Translation and Customisation
From ResourceSpace Documentation Wiki
Contents |
Scope
This document describes how to create an official standard translation and how to create a custom translation for your own system. Components (e.g. JUpload) are to be translated in their respective project and are omitted from this document.
Workflow
Before you start working on an official translation you should verify that no other translator is already working with your language. Post a message in the Google Group for ResourceSpace and announce your intention and ask if someone already has started. You should probably also check with the project's administrator.
Make sure you have the latest svn revision of ResourceSpace. You probably have to update ResourceSpace several times during your work with the translation.
Make all translations.
Create a dbstruct file for the site texts.
Add suitable stop words in config.default.php (commented out as default).
If you have a subversion account you could commit the changed files (don't forget to write a comment that makes sense). If you don't have a subversion account you should upload the changed files to the Google Group and ask someone to commit the files.
You may then go back and correct errors you or other users eventually find and also add new translations when new $lang indices appear.
Standard Translation
All standard site text will fall into one of four categories; main application's texts, plugin applications' texts, site content texts and icons, which are all described below. A stop word list (included in config.default.php) should also be included in a complete translation.
Translating Main Application's Texts
In the “languages” folder, one file must exist per language. If the file does not exist you should copy en.php (it is always complete) and save it with a new name and .php as the file name extension. The name shall be the ISO 639-1 code for your language with a suffix for the country if needed (e.g. sv.php, pt-BR.php).
If the file already exists your first step is to make sure it is complete. Compare it with the en.php and copy missing lines if needed.
Open the file in a standard text editor. The file shall be saved in UTF-8 without BOM.
The text after the equals sign is the text that must be translated. If the $lang is prefixed with a # you have to remove that. The # just means that the $lang is copied from the template but not yet translated.
The language must be added to the language list in the “config.default.php” file.
Translating Plugin Applications' Texts
In the “plugins” folder, there may exist a “languages” folder (all plugins don't use extra texts). Follow the same instructions as above.
Translating Site Content Texts
In the Team Centre, click “Manage Content”. For each content item, you can use the language drop-down box to select the appropriate language version to edit.
When you are finished you shall create a dbstruct file for the site texts (using pages/tools/dbstruct_create.php).
Translating Icons
Some icons contain a text which is to be translated. Decide how to translate the texts and ask Jeff Harmon in the Google Group for ResourceSpace for help. He will probably create the needed icons when he has got the translated texts.
No Preview Icons
These icons are located in the folder gfx/no_preview/resource_type
They are shown if the preview is missing for the resource and there is no file type icon for that particular extension. The filenames of the icons shall be suffixed with the ISO 639-1 code for your language (with an additional suffix for the country if needed). E.g. type1_col_sv.png
Metadata Template Icons
These icons are located in the folder gfx/no_preview/extension
The filenames of the icons shall be suffixed with the ISO 639-1 code for your language (with an additional suffix for the country if needed). E.g. mdtr_es.png
Saved Search Icon
This icon is located in the folder gfx/images
The filename of the icon shall be suffixed with the ISO 639-1 code for your language (with an additional suffix for the country if needed). E.g. save-search_sv.gif
Translating Help Files
In the folder documentation there is a help file named permissions.txt
You may create a new file in your language. The filename of the new file shall be suffixed with the ISO 639-1 code for your language (with an additional suffix for the country if needed). E.g. permissions_sv.txt
Don't forget to update the $lang["documentation-permissions"] to link to the new file.
Missing Features?
If you encounter any missing translation functionality for your language (e.g. you find that the English language uses the same word in several places but with different meanings, and that this is not possible in your language), you may create a patch and send it for review to the project's administrator. If you don't know how to do it yourself you may ask for help in the Google Group for ResourceSpace.
Adding a Stop Word List
Open config.default.php in a text editor. Search for the section with search parameters. Add a comment like this (replace the words between [] with relevant data):
# [language] stop words ([source credit])
Add a line like this (shall be commented out) below the other similar lines. You are not limited to three words, it's just an example.#$noadd=array_merge($noadd, array("[word1", "[word2]", "[word3]"));
The system administrators shall copy all needed stop word lists to config.php and uncomment these.
Custom Translations
Creating Multi-lingual Custom Field Names, Resource Type Names, Field Values etc.
The default field names, resource type names, user group names, report names etc. are translated in the language file. For custom field names, resource type names, field values etc., it may be appropriate for your installation to create these in one language only. However, if multiple language support is required for these areas also, it is possible to use a special syntax when naming these elements to support multiple languages. In System Setup, when naming custom fields, resource type names, field values etc. the following syntax can be used:
~en:Digital Camera~sv:Digitalkamera, ~en:Scanned Negative~sv:Skannat negativ, ~en:Scanned Photo~sv:Skannat fotografi
Take care not to include any additional spaces other than those required between your translated words.
When the source is displayed by the system, for English the text may read “Digital Camera” and for Swedish the text then will read “Digitalkamera”. Additionally when indexing, both values will be indexed so both are searchable, so searching using both languages will work. Note that if the fields are mapped to a file metadata field (e.g. an IPTC field) and the resource is downloaded the field will be exported in its full length, e.g. “~en:Digital Camera~sv:Digitalkamera”.
Creating Customised Site Content Texts
Many site texts are supposed to be completed by the system administrator (e.g. contact us). But there is nothing stopping you from editing all site texts. They are stored in the database and will not be overwritten by a regular update (neither from zip nor via svn update). Note that it is possible to create different texts for different user groups.
Creating Customised Changes to the Main Application's Texts
If you would like to change some of the main application's texts in your own installation you may use a custom translations plugin. Customisations through a plugin will not get overwritten during an upgrade using a zip package and there will be no conflicts during an upgrade through svn. Create a plugin containing a language file for each language used in your system (and also a .yaml file to be able to manage the plugin through the plugin manager). More information could be found in the page Writing_plugins. (You may of course also put any CSS changes and logo graphics in the plugin, effectively creating a customisation plugin.)
Add only your custom changes to the plugin's language files – there is no need to redefine all the strings. The displayed text is the string as defined in:
- The plugin's language file for the current language
- If the string is not already defined above -> The plugin's English language file
- If the string is not already defined above -> The main application's language file for the current language
- If the string is not already defined above -> The main application's English language file
Tips
To get a consistent translation you should select or work out a dictionary to be used. You may also select or work out rules for your language. It's not just about spelling and grammar – you also have to define a style and tone to use.
Here is an example of the Swedish Vocabulary. I think you get it even if this page is written in Swedish. Of course you may copy this page as a start for your own dictionary.
You may also look at the page Swedish Translation - svensk översättning. Use Google Translate to translate it into a language you understand. The English translation is far from perfect but you will probably get a general idea of the concept.
