Calibre2OpdsLocalize

Home Page	User Guide	Calibre2opds Developers Guide				Issues
		Overview	Building	Localization	Customization

Localizing Calibre2opds

This section of the documentation covers the steps involved in getting a version of Calibre2opds localized to a specific language.

Background

Localization is the process of adapting the User Interface and the generated catalogs to use a specific language. Calibre2opds is designed to support localization into the local language. The localization into English is done as part of the standard development of calibre2opds, but for other languages it is necessary for end-users to provide the necessary translated strings.

Note that if a user decides to help with translation it is not necessary that all strings are translated in one go. The calibre2opds will automatically fall back on using the English translations for any strings that are not yet translated to the local language. This means that it is easy to do the localization in small increments (possibly split across many users) without it becoming a dauntingly large task.

Pre-Requisites

These are minimal other than a knowledge of both English (as the start language) and the target language for which the translation is being done.

The tool required is one of:

• A text editor for editing the .propertiesfiles mentioned below. Ideally this editor should be capable of handling text files in UTF-8 format as this the encoding used by the existing .properties files and is the encoding that Java expects. However if you only have an editor capable of handling ANSI format text files then this is a suitable fallback as the calibre2opds maintainers can handle the ANSI to UTF-8 conversion when the revised .properties>file is submitted.

• Microsoft Excel to allow you to edit the Localization spreadsheet mentioned below. Unfortunately other spreadsheet tools are not suitable as they will not be able to run the code embedded into the Excel spreadsheet that is used to generate the underlying Java .properties files.

Getting Started

The translations are maintained in an Excel spreadsheet that is then used to generate the .properties source files that are required by Java. the spreadsheet has embedded macros to import and export these .properties files, and also use some color coding to help identify where new translations might be required.

The files are named as follows:

Filename	Description
localization.xls	This is the Excel spreadsheet that be used to generate all of the .properties files.
localization_XX.properties	This will be the set of translated strings for the language code identied by XX
enumerations_XX.properties	This is a set of strings for a hnumber of cases where a choice of values is offered in a drop-down list

There are two basic routes to obtaining the localization files:

• Download localization files: You can download just the localization files using a web browser from here on gitHub. You can download just the .properties file that you are going to work on, or the Localization.xls Excel spreadsheet that contains the master copies of translation text strings for all languages currently supported (from which the .properties files can be generated).

• Download full source: If you are interested in also Building Calibre2Opds from source then you can get the latest calibre2opds source using the process specified here in the section on Building calibre2opds. One advantage of going the full source approach is that you after doing some translations you can rebuild calibre2opds to test out of the results of your changes before submitting them back to the calibre2opds developers. Look in the OpdsOutput/src/main/resources folder (relative to where you downloaded the calibre2opds source) for the localization files. If you are doing files for a new language they would be added to this folder.

Making Changes

The easiest approach involves editing the language specific .properties files with a text editor. If editing these files then you should edit any of the translation stings that appear wrong or are missing.

If there is already a partial .properties file for the language you intend to work on, then entries that are missing a translation are identified in the ,properties files by the fact that they start with #EN#. For such entries as well as providing the translated text you should also remove the #EN# from the start of the line. The translated strings are those to the right of an '=' sign as shown in the example below.

If you are going to work on a language that is not currently supported, then you should start with the English .properties files and replace the English text with appropriate translated text.

An alternative if you have Microsoft Excel available is to alter the localization.xls spreadsheet to make changes as this is the master repository for all the languages and helps with keeping different languages in sync with the source. When using the spreadsheet you will find that any the cells for strings for which no translation is currently available will be highlighted in yellow which makes it easy to spot missing/needed translation strings. If you are working on a language that is currently not supported simple add a new column for that language to the spreadsheet. If the cell is highlighted in yellow, but the translated text will be identical to that in the column for English then this does not matter as the English text will automatically be used in such cases. As long as you have Excel available to you then you can run the Export command at any time to regenerate a full set of .properties files that match the current spreadsheet.

A sample from a properties file might look like:

 boolean.no=non
 boolean.yes=oui
 splitByLetter.letter={0} débutant par {1}
 # where {0} is the wording for the element
 # and {1} is the letter
 # Example : Tags starting with F
 # or : Authors starting with A
 home.title=Catalogue principal
 link.fullentry=Entrée complète
 # titles with page number
 #************************
 title.nextpage=page suivante ({0} sur {1})
 # where {0} is the page number and {1} is the total number of pages
 # Example : next page ( 2 of 4)
 title.lastpage=page suivante (dernière)
 title.numberOfPages={0} ({1} pages)
 # where {0} is the numbered wording for the item and {1} is the total number of pages
 # Example : 43 authors (3 pages)

Any lines that start with # as the first non-space character are comments. These are for guidance only and should be left unchanged (except for the special case of line starting with #EN# mentioned above). Sometimes they will give information about any special requirements on the format of the translated string.

Lines that specify translation strings are of the form:

keyword=string

You should never change or add keywords as these are set by the programmer. The string part is the language specific text that will be used.

Using Formatting in localization strings

It is possible to include special characters in the localization strings that are used as part of the calibre2opds GUI. This is done by following the Java standards for embedding special characters in strings. The one that is most likely to be of relevance is the use of the \n sequence to represent a newline (however see the use of HTML style tags as described below which gives even more control).

Another technique that can be used is to start a string with <html> and then many HTML tags can be added to help with formatting. This technique is most useful for formatting within tooltip text and error message text which can be quite long. If you use
to force line breaks and
,br> to get new paragraphs then you can stop very wide dialog boxes or tooltip boxes from being displayed. Note that for some reason when using this technique

tags do not seem to have much effect, so you need to use

to get a new paragraph. It is not possible to do the same for strings that are part of the generated catalogs. If a real requirement arises for this then at the very least it would require changes to be made at the source code level in the localization handling within calibre2opds. If anyone working on localization can thinks they have a good case for being able to use such a facility then please raise it as a feature request via the calibre2opds issue register.

Testing Changes

The calibre2opds maintainers will not be in a position to test that a localization in a particular language is correct. A check will be made that the translations have been correctly added and that they can be invoked, but not that the translated strings make sense. This needs to be done by someone who is fluent in the language in question.

There are two basic ways of testing localization changes:

• Following the steps for building calibre2opds on your own system and adding the localization files to the folder. We have deliberately made the process of rebuilding calibre2opds a simple task that does not require any detailed knowledge of programming or the Java language. If you go down this route then you can test out localization changes before you submit them for inclusion into the main source tree.

• Submit the changes to the calibre2opds maintainers (as identified below) and requesting that you are given access to a build incorporating the changes you have submitted. This is the way to go if you do not feel confident in building calibre2opds on your own system

Submitting Changes

After you have made any changes, you will need to submit the changes back to the calibre2opds maintainers and your changes will be validated as being correctly formatted and assuming no problems are spotted they will be added into the main calibre2opds release branch in GoogleCode.

There are various ways of submitting the changes:

• Using the calibre2opds Issue Register which is relatively intuitive to use. This is the preferred way as it helps with tracking such changes If there is already an issue for localization in the language you are working on then add a comment and attach any updated files. If there is no existing issue, then create a new one and then add the comment and attach the files.

• Email the changed files to one of the calibre2opds developers. If you go down this route then the calibre2opds maintainers can also use provide private builds for testing out localization via attaching test builds that can be downloaded to an issue. However we would prefer it you could use the Issue register approach mentioned above as it helps with tracking progress.

• Submit the changes as a revision to GoogleCode. This will require you to have set yourself up with appropriate privileges so it is not anticipated that many users will use this route. It is anticipated that only those who are going to become active calibre2opds developers and be working on updating calibre2opds source code are likely to want to go down this route.

Once a localization change has been submitted and accepted then it will be incorporated into the calibre2opd source ready for inclusion into the next calibre2opds release. Once the maintainers have added your changes and uploaded the updated translations to GoogleCode, they will also be available immediately from GoogleCode to others who want to work on localization. You will also be able to see from the source code change history that the changes have been incorporated.

Note that there is no issue with providing updates as a number of small sets of changes rather than one large change. This has the advantage that the changes you DO make get incorporated into the calibre2opds main source branch as rapidly as possible, and that you can see the effect of your changes at an earlier stage.