Rockbox Language System v2


GOALS

* Possibly different original strings depending on target player

* Possibly different translations depending on target player

* Possibly different voice strings depending on target player (and of course
  optionally no voice at all for a given phrase)

* No more having strings for other players around (like how Archos Recorders
  currently load Archos Player strings and vice versa)

* Feature translated/voiced plugins

File format of human readable/editable Language Files
=====================================================

 * lines starting with # are treated as comments

 * strings are always "within double quotes"

 * special right-side-of-colon keywords exists: NONE, DEPRECATED etc

 * there's one <header> section and numerous <phrase> sections

 * Within <source>, <dest> and <voice> you can use comma-separated lists of
   targets on the left side of the colon. A target on the left side can also
   be a "wildcard" as in "*recorder*" for all targets that have the string
   recorder somewhere in its name.

<header>
  # language is the local name of the language this file is for
  language: "svenska"
  # id is a unique numeric decimal value identifying this language
  id: "13"
  # version is a numerical value that MUST be increased when non backwards
  # compatible changes are made. This number is only used from the english
  # "base" language file.
  version: "1"
  # A set of authors of the translation
  authors: "My Name, His Name, Her Name"
</header>

<phrase>
  id: "LANG_ID_NAME"
  desc: "english descripton of where or how the phrase is used"
  user: "name of plugin(s) that uses this phrase (use main or blank for core)"

  <source>
    *: "generic phrase"
    recorder: "phrase adjusted to the recorder"
    h100, h300: "phrase adjusted to h100 and h300"
  </source>

  <dest>
    *: "generic translation"
    player: "translation adjusted for the player"
    h300: NONE # blanked for this target
  </dest>

  <voice>
    *: "generic voice string for this string"
    ondiosp: "voice adjusted for ths ondiosp"
  </voice>

</phrase>

Target Players
==============
These are names used for translation targets:

Name            Model ID

player          1
recorder        2
recorderv2      3
fmrecorder      4
ondiosp         5
ondiofm         6
h100            7
h300            8
gmini120        9
gminisp         10

(this list of numericals should be identical to the list used in the configure
menu)

Binary Language Output Format
=============================

File header must include:

* Lang file identifier (16 bits)
* Version number (16 bit, 16 bits is enough to
  make a future wrap of this number not matter too much)
* Model ID (8 bit, for which target the file was made)

* Users name max length field (8bit)
* Number of users in the index (16 bit)

* Sorted index of users, and for each user:
  - name (using a fixed field length)
  - offset to translation data for this user (32 bits)
  - size of the translation data in number of bytes (16 bits)

* A series of translation data blocks, that each contain a series of:

 [16bit ID][string][zero byte]

Binary Voice Format
===================

* Encoding type (MP3, MP3_BITSWAPPED, etc)
[to be filled in]


Using this system in plugins
============================

* Source-wise

  genlang will build a "lang-[name].h" header file for each user specified in
  the given translation source file, and a C source file for the strings. A
  plugin called "saltmine" will get a "lang-saltmine.h" header file with the
  necessary language IDs and macros setup for usage and a "lang-saltmine.inc"
  that contains the actual array with the default built-in strings. In the
  current one-source-file-per-plugin build setup, this C file will initially
  be #included but this should not be the long-term solution. When we make it
  get compiled/linked separately, we will change it to become a real .c file.

  It will of course also build the core lang.[ch] files.

* Run-time

  binlang, and the general Rockbox build system, will create (default)
  language files for specific languages that contain translated strings for
  many/all plugins (as well as the core). Plugin authors and users will
  normally not have to bother or care about this.

* Implementation

  When a plugin is loaded by Rockbox, it will also check the current language
  file to check for a plugin-specific translation. If there is one, it will
  load that chunk and setup the strings accordingly.

  To enable new plugins (with translations) to get updated independently,
  Rockbox supports plugin-specific language files. Rockbox will check for and
  load language files like this:

  1. .rockbox/langs/plugins/[plugin]-[language].lng
  2. .rockbox/langs/[language].lng

  Existance of file 1 overrides the usage of file 2.