|
AddingTranslations
Adding Additional Language Translations to Tunnelblick
Tunnelblick is an OS X Graphical User Interface (GUI) for the OpenVPN free and open-source program, which maintains VPN "tunnels". It provides easy-to-use control of OpenVPN server and/or client connections. For more information, including wikis and a discussion group, see the Tunnelblick home page. This document describes how to add additional language translations to Tunnelblick. This document may be obsolete! The latest versions of this document and related documents including release notes, FAQ, and instructions for building Tunnelblick from the source code may be found in the Tunnelblick Wiki. This document contains the following sections: How Translations WorkAlthough some applications have elaborate structures to specify translations, Tunnelblick's is simple. Inside of Tunnelblick.app there is a folder for English, and a folder for each language that has been translated. Each language folder (except English) has as its name the ISO-639-1 two-letter abbreviation of the language and an extension of "lproj". For example, "JA.lproj" is the folder with Japanese strings, "ES.lproj" is the folder with Spanish strings, etc. The one exception is English, which is named English.lproj. That is because Tunnelblick's original development language was English. NOTE: Prior to r255, which will be incorporated in Tunnelblick versions 3.0b24 and up, all .lproj folders had the English name of the language, instead of the ISO-639-1 two-letter abbreviation of the language. Each of these folders contains a "Localizable.strings" file. These files contain a series of lines that look like this: /* Button */ "Disconnect" = "Desconectar"; The first line, /* Button */, is a hint about what the string is used for -- this one tells you that the string "Disconnect" is for a button. Other hints may indicate a string is for the title of a window, or the text of a window, or is a status message from OpenVPN. The second line has two strings, separated by an equal sign and followed by a semicolon. The first string is in the language that the application was developed in (English), and the second string is in the "target" language. In the example above, from the "ES.lproj" folder (Spanish), "Disconnect" is the English string, and "Desconectar" is the equivalent in Spanish. You can edit this file in TextEdit (but you need to open it in a special way, see Opening Localizable.strings Files) change the second string on each line, and send it back to the Tunnelblick project for incorporation into Tunnelblick. You can, if you wish, put it into your own copy of Tunnelblick, too (see Adding Your Translations to Your Copy of Tunnelblick). First Translation of a LanguageIf you are the first translator for a language, the file you have will use will be a copy of English.lproj/Localizable.strings. (Make your own copy if necessary.) The file will have lines such as the following: /`*` Connection status `*`/ "AUTH" = "Authorizing"; /`*` Window title `*`/ "Authentication failed" = "Authentication failed"; /`*` Checkbox name `*`/ "Automatically connect on launch" = "Automatically connect on launch"; /`*` Button `*`/ "Cancel" = "Cancel"; Notice that, in this file, both of the strings on each line are in English (sort of). The string "AUTH" is a string describing a connection's status -- what it is doing -- in this case, the status is something called "AUTH". The second string is the string as it should be displayed in English -- this is what you as translator are to replace. Note that for the last three examples, both strings are identical. That is more common. The program requests that the title of a window be "Authentication failed", for example, and, in English, that should be displayed as "Authentication failed". Translation consists of replacing the second string on each line with the target language's equivalent, using the hint on the line above the strings. Editing or Adding TranslationsIf you are editing a file that has already been party or fully translated (perhaps fixing typos or translating new strings required by new Tunnelblick features), you will be editing the "Localizable.strings" file in one of the .lproj folders. "Localizable.strings" will have a "/* Needs Translation */" comment before every line that appears to not have been translated. (A program we use to create these files decides that a line needs translating if the left-side and right-side strings are identical, which does not always mean they need translation, but is a reasonable guess.) You should remove the "/* Needs Translation */" comments on any strings that you have translated. If a String is the Same in Both LanguagesIf a string is the same in both the development language and the target language, then put a hint of /* TRANSLATION SAME AS DEVELOPMENT */ before the string. For example, /* TRANSLATION SAME AS DEVELOPMENT */ /* Button */ "OK" = "OK"; This helps the program which process the strings files understand that the string does not need translation. Opening Localizable.strings FilesYou can edit Localizable.strings files in TextEdit, but you need to open them a special way. If you double-click them, or just File | Open them, things might look OK, but they aren't. The .strings files are in a special format called UTF-8, and need to be opened, edited, and saved in that format or bad things happen (such as losing diacritical marks or changing characters into different characters!) To open one of the .strings files in TextEdit:
Now you can edit the file. When you are done, be sure to save it. If you do a "Save As", be sure to save it as "Unicode (UTF-8)". Here is what the bottom of the "Open file" dialog window should look like when you click the "Open" button:
Weird Characters in the StringsSome of the strings have character sequences of "\n". This causes a line break when the text is displayed. A sequence of "\n\n" would cause a line break followed by an empty line. Some of the strings have %@, %d, or other special sequences of characters. They indicate a place where some other item (a filename, a number, etc.) will be inserted into the string. Usually that's all there is to it. However, when there are two or more such items in one string, the target language may need to use them in a different order than English uses. Here's an example: for English speakers, one of the distinctive features of the character Yoda in Star Wars was the way he spoke -- he spoke backwards. For example, he would say "Hot the food is", when the usual way to express that in English is "The food is hot". If the line in Localizable.strings was "The %@ is %@" = "The %1$@ is %2$@"; we would translate that into Yoda's English by changing it to "The %@ is %@" = "%2$@ the %1$@ is" (We'll ignore the fact that %2$@ needs to be capitalized because it now starts a sentence.) Adding Your Translations to Your Copy of TunnelblickIf you made the first translation of a language, here's how to put your modified .strings file into your copy of Tunnelblick:
You're done. The copy of Tunnelblick.app on your Desktop now has your translations. If you edited an existing translation, here's how to put your modified .strings file into your copy of Tunnelblick:
You're done. The copy of Tunnelblick.app on your Desktop now has your translations. PLEASE USE THE TUNNELBLICK DISCUSSION GROUP FOR COMMENTS OR QUESTIONS |
