Build language DLLs into bin\Languages, so that the executables pick up language...

[TortoiseGit.git] / Languages / README.txt

Translations\r
============\r
\r
TortoiseGit is still in development so translations of all resources is\r
also a work 'in progress'.\r
\r
General\r
-------\r
The TortoiseGit project uses the web-based Transifex platform for\r
managing translations:\r
https://www.transifex.com/projects/p/tortoisegit/\r
\r
This should make it easier for new translators to get started. If you\r
want to help to translate TortoiseGit, please register an account a\r
transifex.com (you can also login using your google account), then\r
request membership of one of our translation teams or request to create\r
a new team, if your language is not yet listed. If you want to\r
translate into a language that has different locales and you *really*\r
need the second locale, add the two letter ISO-3166 locale code. If\r
you're not sure about your country code, look here:\r
http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html.\r
Please keep in mind that we would like to have as few translations as\r
possible that cover as many languages as possible (in order to reduce\r
the work needed for keeping all translations up to date).\r
\r
For most (unlisted) languages you do not need to start all over. A large\r
amount of translated strings can be reused from the TortoiseSVN project:\r
Just request a new language team and contact the TortoiseGit developers!\r
\r
Translating\r
-----------\r
There are some notes and hints for translating:\r
\r
When translating please try to adapt the naming conventions used by the\r
Git team. Their translations can be found here:\r
https://github.com/gitster/git/tree/master/po\r
\r
When translating on transifex.com there you might see red symbols in the\r
original text such as "⇥", "⏎", "↩" (you need an UTF-8 aware editor to\r
see the the three different symbols here). DO NOT COPY these into the\r
translated text as this might break certain semantics. "⇥" means that a\r
tabulator is needed at that position. "⏎" and "↩" indicate that a new\r
line should be inserted there. For "⏎" just press enter, "↩" needs\r
special attention as well as the tabulator character.\r
ATTENTION: Right now there is a bug on transifex so that the tabulator\r
character and the "↩" new line character cannot be inserted using the\r
keyboard. Workaround: Click on "Copy source string" and then carefully\r
replace the text before and after the tabulator resp. the "↩" new line\r
character.\r
\r
Character sequences such as "%i", "%d", "%ld", "%I64d", "%u" and "%.1f"\r
(will be substituted by a number each) and "%s" (will be substituded by\r
a string/text) MUST be included in the SAME ORDER as in the original\r
text (otherwise the program will crash at run-time). These sequences are\r
called "format specifiers" (see\r
https://msdn.microsoft.com/en-us/library/75w45ekt.aspx for more\r
information).\r
There is only one exception: Only if a exclamation mark, a number and\r
another exclamation mark such as "!1!" is between the per cent sign and\r
the specifier such as "%!1!s" or "%!3!d" then the order can be exchanged\r
(the number between the exclamation marks indicates which input will be\r
inserted at run-time).\r
\r
An ampercent (&) before a letter such as "&Open" indicates that "O" is\r
an accelerator key in the current context (e.g., in a menu or in a\r
window) which can be accessed by pressing the key or ALT+key (depending\r
on the context; open a menu with ALT+key choosing an option within the\r
menu just press the key). These should be unique in their contexts\r
otherwise they won't work - try to use the same letters as in the\r
original text or test which other keys don't conflict (and are common in\r
your language).\r
In order to see them, just press the ALT key then the respecting\r
characters will be shown underlined.\r
\r
There is also a second type of accelerator keys (such as CTRL+F). These\r
are represented as specially formatted strings which look like\r
"ID:xxxxxx:VACS+X" and are designed for localized accelerator keys.\r
Format is: "ID:xxxxxx:VACS+X" where:\r
   ID:xxxxx = the menu ID corresponding to the accelerator\r
   V = Virtual key (or blank if not used) - nearly always set!\r
   A = Alt key     (or blank if not used)\r
   C = Ctrl key    (or blank if not used)\r
   S = Shift key   (or blank if not used)\r
   X = upper case character\r
e.g. "V CS+Q" == Ctrl + Shift + 'Q'\r
ONLY Accelerator Keys with corresponding alphanumeric characters can be\r
updated, i.e. function keys (F2), special keys (Delete, HoMe) etc. will\r
not.\r
Below the translation textbox, there is a field "Developer note:". There\r
you can find further information for accelerator keys, e.g.:\r
"Accelerator Entry for Menu ID:57636; 'Find' Accelerator Entry for Menu\r
ID:57636; '&Find\tCtrl+F'". This means that this accelerator is used\r
for the menu entry "&Find" (which also has a local accelerator key "F"\r
within the menu; there is no need that both accelerator keys include\r
the key - e.g. it's common to use 'x' for "E&xit" within the "File"\r
menu and CTRL+W as global accelerator key).\r
\r
We hope that these hints will answer most questions. If you have any\r
further question, feel free to ask (e.g., on the mailing lists)!\r
\r
What now?\r
---------\r
That's all you have to do. We'll take care of creating the resource\r
dlls and installers for the different language packs.\r
\r
Our goal is to provide language packs starting with the next releases\r
as soon as more than 50 % of the strings are translated on the offical\r
TortoiseGit download page (https://tortoisegit.org/download).\r
\r
Technical details\r
-----------------\r
The TortoiseGit project uses gettext PO (portable object) files for its\r
translation. PO files are plain text, so you can even translate using a\r
normal text editor. The only thing you have to take care of is that the\r
editor can handle the UTF-8 charset. There is a wide range of specialized\r
tools out there that can handle and manipulate PO files (such as poEdit,\r
http://poedit.sourceforge.net).\r
\r
You can also create your personal translations. Just use the\r
"Languages/Tortoise.pot" file as a template for your own "Tortoise_CC.po"\r
file and start translating it.\r
\r
Building your own dlls\r
----------------------\r
If you want to test the translations you made yourself, you need three things:\r
\r
- The "raw" resource dlls for your version of TortoiseGit. Other dlls\r
  won't work. The TortoiseGit teams provides those for every stable release.\r
  You can find them in the release folder on https://download.tortoisegit.org/tgit/\r
  named "TortoiseGit-LanguageDlls-X.X.X.X-(32|64)bit.7z" (you might need 7-Zip for unpacking)\r
- A po file containing the translations for your language.\r
- The ResText utility that is used to insert the data from the po file\r
  into your resource dlls. This tool is also included in the archive in which the "raw"\r
  resource dlls are included.\r
\r
Once you got all needed files, you run:\r
\r
    restext apply TortoiseProcLang.dll TortoiseProcNNNN.dll Tortoise_CC.po\r
    restext apply TortoiseMergeLang.dll TortoiseMergeNNNN.dll Tortoise_CC.po\r
    restext apply TortoiseIDiffLang.dll TortoiseIDiffNNNN.dll Tortoise_CC.po\r
    restext apply TortoiseGitUDiffLang.dll TortoiseGitUDiffNNNN.dll Tortoise_CC.po\r
    restext apply TortoiseGitBlameLang.dll TortoiseGitBlameNNNN.dll Tortoise_CC.po\r
\r
where NNNN is your four digit country code (1031 for germany)\r
and CC is your 2 letter country code (de for germany)\r
\r
You can find the four digit country code at\r
https://msdn.microsoft.com/goglobal/bb964664.aspx\r
under the column LCID dec.\r
\r
After successfully creating your dlls, copy them into\r
"C:\Program Files\TortoiseGit\Languages".\r
Now you should be able to select your language from the combobox on the\r
TortoiseGit main setting page.\r