LangFiles < Main

Downloads
release
dev builds
extras
themes
Documentation
manual
wiki
device status
Support
forums
mailing lists
IRC
Development
bugs
patches
dev guide
Wiki > Main > DocsIndex > LangFiles
---+!! Lang Files Explained

%TOC%

---++ Creating new languages

Copy the english.lang to [your language].lang and change all strings within the &lt;dest&gt; and &lt;voice&gt; tags.

---++ Prerequisites to be able to translate

First of all, you need to speak the language you're translating to fluently. This cannot be stressed enough. You should either be a native speaker, or having spoken the language daily for years. High-school classes are not enough. Machine translations are completely unacceptable.

To avoid manual (and error-prone) diffing, copy and pasting and so on, use the script called [[http://svn.rockbox.org/viewvc.cgi/trunk/tools/genlang][genlang]] with its -u option.

Note: If you don't have or want a build environment, it should be possible to download the script to your pc and do it all without the build environment. Get a perl interpreter if you don't already have one, for example [[http://www.activestate.com/Perl.plex][ActivePerl]].

So be sure you can start the genlang script either way, or opt for the hard way by doing it all yourself.

---++ Preparation every time you update

The translation is always done "from" English, so [[http://git.rockbox.org/?p=rockbox.git;a=blob_plain;f=apps/lang/english.lang;hb=HEAD][english.lang]] is the master file. Monitor this file if you want to be sure to keep "your" language up to date.

The only one step of preparation you have to do every time you want to update "your" language is to run that script:

Bring yourself to the =/apps/lang/= directory (or to the directory where english.lang and yourlang.lang reside if you work without build environment). Don't forget to update the file ( =svn up english.lang= or just a fresh download). Run  genlang like the following line:

<verbatim>
 ../../tools/genlang -u -e=english.lang yourlang.lang > yournewlang.lang
</verbatim>

This assumes you are working "from" English, as usual, your outdated language file is called _yourlang.lang_ and you want to get the merge to _newyourlang.lang_.

Now that genlang has merged the new changes from English to _newyourlang.lang_, you can go ahead with the actual work of translation, by opening the file in your favorite text editor. The new file has added comments starting with ### marking where you (might) need to edit the file.

---++ The lang file format

I'm afraid we have to look into the format of lang files now. Every string needed in RockBox has a voice clip, this is why we can call such a pair a "phrase". Every phrase has absolutely unique identifier (called =id=), it has a description that tells you the context so you can select the wording (called =desc=), it has the original English string (called =source=), it has a string specially for the voice clips (called =voice=) and it finally has the string in your language (called =dest=).

All =source/dest/voice= strings must be written within double quotes ("). There are a few keywords that can be used that don't use quotes, but they are special and are detected by the absence of quotes.

When updating a language, you are asked to solely change the =dest= and =voice= strings.  Changing =id=, =source= or =desc= will either break-up everything or turn the subsequent update job into real pain.

Comments start with the hash-sign ('#', also called hash (UK) or pound (US) key in English; 'Raute', 'Viereckchen', 'Lattenkreuz' in German; or 'Kanalgitterchen' in Austrian. No joke, but funny :-) )

Lang files *must* be saved with *UTF-8* encoding.

---++ Langv2
As of April 4 2006, we've converted to a new language file format and system. We now allow different strings for different targets, and you can now make sure that the string is correctly saying things for each model. All phrases have a default string like: =*: "default"= that will be used if no other string matches for the particular model you build the language for. If you want a particular string for the iriver iriverh300 series you'd write it like: =iriverh300: "iriverh300-specific string"= (and of couse use the default string too on the line below).

The target names used for this are picked from the configure script and are set in the MODELNAME variable in the root Makefile.
Currently, they are:
|*Target*|*Target string*|
|*Archos*||
|Player/Studio|*archosplayer*|
|Recorder|*archosrecorder*|
|FM Recorder|*archosfmrecorder*|
|Recorder V2|*archosrecorderv2*|
|Ondio SP|*archosondiosp*|
|Ondio FM|*archosondiofm*|
|*iaudio*||
|M3|*iaudiom3*|
|M5|*iaudiom5*|
|X5|*iaudiox5*|
|Cowon D2|*cowond2*|
|*ipod*||
|1G and 2G|*ipod1g2g*|
|3G|*ipod3g*|
|4G gray|*ipod4g*|
|Color/Photo|*ipodcolor*|
|Video (5G)|*ipodvideo*|
|Mini 1G|*ipodmini1g*|
|Mini 2G|*ipodmini2g*|
|Nano 1G|*ipodnano1g*|
|Nano 2G|*ipodnano2g*|
|*iriver*||
|iriver H10 20GB|*iriverh10*|
|iriver H10 5GB|*iriverh10_5gb*|
|iriver H100/115|*iriverh100*|
|iriver H120/140|*iriverh120*|
|iriver H320/340|*iriverh300*|
|*Olympus*||
|M-Robe 100|*mrobe100*|
|M-Robe 500|*mrobe500*|
|*Samsung*||
|YH-820|*samsungyh820*|
|YH-920|*samsungyh920*|
|YH-925|*samsungyh925*|
|*Sansa*||
|c200|*sansac200*|
|Clip|*sansaclip*|
|e200|*sansae200*|
|e200 Rapsody|*sansae200r*|
|e200v2|*sansae200v2*|
|Fuze|*sansafuze*|
|*Toshiba*||
|Gigabeat F/X|*gigabeatfx*|
|Gigabeat S|*gigabeats*|


---++ The translation

Mainly said, any resource that needs attention has a '###'-comment. I will now list the 'scenarios' I know and how I think they have to be handled.

---+++ Deprecation
If a string is not needed anymore, it's not allowed to delete it in the master file.  Therefore, they are marked by writing ="DEPRECATED"= to the description. The todo-comment that will appear in the file you're editing is ="### The 'desc' field differs from the english!"= followed by the OLD description line. This is by far the simplest work to do when updating language files.

A deprecated string is not needed anymore. 

A deprecated string should be written as the following in the lang file. This example snippet deprecates the destination string for all targets:

<verbatim>
<phrase>
  id: LANG_FOO
  desc: DEPRECATED
  <source>
    *: ""
  </source>
  <dest>
    *: deprecated
  </dest>
  <voice>
    *: ""
  </voice>
</phrase>
</verbatim>

---+++ Added Strings
If a new string has been found in english.lang, =genlang -u= will prepare a resource for you, so you only have to remove the comments and translate the string. Example:
<verbatim>
###
### This phrase below was not present in the translated file
<phrase>
  id: LANG_STEREO_WIDTH
  desc: in sound_settings 
  <source>
    *: "Stereo width"
  </source>
  <dest>
    *: "Stereo width"
  </dest>
  <voice>
    *: "Stereo width"
  </voice>
</phrase>
</verbatim>

---+++ String Removal

The lang format allows you to completely remove a string for a particular target's language file by using the =none= keyword:

<verbatim>
  <dest>
     *: "fancy LCD bitmap rotation enabled"
     player: none
  </dest>
</verbatim>

Note however that this completely removes the string from the output and thus it may very well break backwards compatibility when you do this. Carefully consider deprecating the string instead.

---+++ Translation style

The translation should feel as correct as possible to speakers/readers of your native language you're translating this to. This means that you should follow the rules of the language you're translating to, and not try to imitate the English version. For example with capitals, you should not capitalize anything other than what would be done if you were writing the text from scratch. Also try as much as possible to avoid using English words, as tempting as it may be, unless it's very commonly known and in daily use in your language (and not just among tech-interested people).
---

Your main work is done if you can't find any '###'-comment anymore :-)<br>
Now, go ahead and see if you made a mistake before posting your work in the [[http://www.rockbox.org/tracker/newtask/proj1][patch tracker]].<br>
If you are able to create a patch with your changes against current SVN we prefer that but the whole .lang file is just fine.
Be sure to drop a line on the mailing list after that so your updated file will get committed as soon as possible.
It would be a bummer if somebody else would be doing the same work a week later.

---++ Safety checks

Note:  %RED%strings are always "within double quotes", *even the empty ones* %ENDCOLOR%

Just for safety, I do a few checks. I use a file differ ([[http://www.scootersoftware.com/][BeyondCompare]], will be available for linux too in a while) for this.

   1. *check:* comparing the _newyourlang.lang_ to _yourlang.lang_. This allows you to see WHAT you changed, just in case you made a big mistake.
   2. *check:* comparing the _newyourlang.lang_ to _english.lang_. These files should only differ in new-strings and comments.
   3. *check:* if genlang complains when making a binary .lng file. This is easily done by placing _yourlang.lang_ inside the =apps/lang= directory inside your source tree and performing a 'make'. If you do not have a Rockbox development environment set up, this can be done from the command line using genlang with the following swithches: <br>
   ==../../tools/genlang -e=english.lang -t=yourtarget:features -i=targetid -b=yourlang.lng yourlang.lang== <br>
      a.  _yourtarget_ is the target string that the Rockbox build system uses, for example "iriverh300" for iriver H300, after your target enter a colon separated list of "features" supported by your target, see apps/features.txt in the Rockbox svn for which ones are defined for each target.  The argument for 'i' is the _id number_ that the build system uses for your target, for example '10' for the H300. <br>
      a. To find the target string and id number for your target see the tools/configure script in the Rockbox SVN, or you can find them in a current Rockbox build by opening the file =/.rockbox/rockbox-info.txt=. <br>
      a. If =genlang -b= does not complain about anything, then this means that you didn't make a big mistake.<br>
   4. *check:* the experiment on oneself: copy the _yourlang.lng_ to your rockbox (/.rockbox/lang), switch the language, and try it out.

---++ Current status
---+++!![[http://translate.rockbox.org/][Translations status overview on translate.rockbox.org]]
I	Attachment	Action	Size	Date	Who	Comment
EXT	langstatus	manage	1.6 K	23 Aug 2006 - 03:09	JonasHaeggqvist	Language status script, generates the table on this page
r57 - 30 May 2012 - 21:05:32 - DominikRiebeling
Parents: DocsIndex