Localization

User Guide Overview Building Localization Customization Issues

Calibre2Opds Localization

Background

Calibre2opds is designed to support localization into the local language. The localization into English and French 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 fall-back as the calibre2opds maintainers can handle the ANSI to UTF-8 conversion when the revised .propertiesfile 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 GoogleCode.   You can download just the .properties file that you are going to work on, or the Localization.xls Excel spreadhseet 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 ninteresting in also Building Calibre2Opds from source then you can get the latest calibre2opds source using the process specified here in the Development section.  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 beofre submitting them back to the calibre2opds developers.  Look in the OpdsOutputsrcmainresources 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 specifc text that will be used.

Using Special Characters 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.

It is not possible to do the same for strings that are part of the generated catalogs.  If a real requriement 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 ahve 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 positition 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 localisation 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 identifed below) and requesting that you are given access to a build incorprorating 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 maintainerscan 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 anticpated that many users will use this route.   It is only those who are going to be working on updating calibre2opds source code who are likely to want to go down this route.

Once a localisation 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.

  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 27 other followers

%d bloggers like this: