mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-11-06 11:23:45 +00:00
248 lines
10 KiB
Plaintext
248 lines
10 KiB
Plaintext
|
|
Localization/Translation FAQ
|
|
(2007-2018)
|
|
|
|
by Ran Rutenberg, Pavel Sanda, Michael Gerz
|
|
|
|
|
|
PART I - Interface translation
|
|
------------------------------
|
|
|
|
This file is mainly intended for those who have no or little experience using
|
|
.po files, but want to contribute by translating the LyX interface (i.e. menu
|
|
and dialog items, console messages) into their native language.
|
|
|
|
|
|
1) WHERE DO I START?
|
|
|
|
The file you need to edit is an xx.po file where xx stands for your language's
|
|
two letter code. For a list of language codes look at:
|
|
|
|
https://www.gnu.org/software/gettext/manual/html_mono/gettext.html#Language-Codes
|
|
|
|
If you want to start from scratch then you should obtain a copy of the lyx.pot
|
|
and name it after your language. German would be for example de.po and Polish
|
|
pl.po. This file is generated in the "po" directory of the source tree during
|
|
the compilation.
|
|
|
|
There are basically two source trees you can start to work with - trunk
|
|
(development version) and branch (stable version). Unless the development
|
|
version is shortly before release it is better to start your translating
|
|
work on the stable version. If you have no idea how to get those trees you
|
|
can follow https://www.lyx.org/HowToUseGIT page.
|
|
|
|
|
|
2) HOW DO I EDIT PO FILES?
|
|
|
|
PO files can be edited with any text editor available for your system (e.g.
|
|
Vim, jEdit etc.). Yet another option is to use a specialized editor for .po
|
|
files. You can e.g. use the editor "Poedit", Linux users can
|
|
additionally use e.g. "Lokalize". Using these editors usually makes things easier
|
|
as they have many tools to assist the translator.
|
|
If you use Poedit, please uncheck in its settings the option to break lines after
|
|
80 characters.
|
|
|
|
|
|
3) WHAT DO I NEED TO TRANSLATE?
|
|
|
|
If you are using a simple text editor you should translate the strings that
|
|
appear in the msgid line and write the translation into the msgstr line. Note
|
|
that a "#, fuzzy" line is just a hint for translation from compiler - in order
|
|
to get the translation of the current item working you have to delete this
|
|
line. It is recommended that you take a look at another .po file - that way you
|
|
can get an idea of what to do. If you are using a specialized po editor
|
|
then you will see in it the untranslated strings and a place to write your
|
|
translation for them.
|
|
|
|
|
|
4) WHAT SHOULD I DO WITH THE '&', '|', '$, '%' {} AND [[]] CHARACTERS?
|
|
|
|
'&' stands for underlined characters (shortcut) in dialog boxes.
|
|
'|' stands for underlined characters in menus.
|
|
|
|
These chars should be somehow used in your translations, however you'll have to
|
|
invent your own working shortcuts for dialog and menu entries and resolve
|
|
possible conflicts of the same shortcut chars in one menu...
|
|
|
|
You will be informed about conflicts in the terminal if you try to access the
|
|
menu.
|
|
|
|
Note that, in the case of '|', if more than one character follows, this means
|
|
that LyX will try each of them in turn and use the first one that is not yet
|
|
used by another entry in the menu. That way, you can define alternative shortcuts
|
|
in the case one works in one context only, and another one only in another. You
|
|
can use this possibility also in translations, but please use it only if no
|
|
single shortcut that fits could be found.
|
|
|
|
Note also that there are already used global shortcuts (such as p k x c m s a)
|
|
and you should avoid using these characters for first-level menu shortcuts.
|
|
|
|
'$' and '%' are usually used as handlers for formatting or variables to be
|
|
inserted into the strings. Character sequences like %1$s or %1$d MUST also
|
|
appear in your translations! Please take them exactly as they are or you may
|
|
experience crashes when running LyX.
|
|
|
|
[[Context]] is used to distinguish otherwise identical strings, which could
|
|
have different translations depending on the Context. It can also be used to
|
|
indicate what is substituted for a placeholder. [[Context]] appears only in
|
|
msgid string and should not be repeated in the translated version.
|
|
|
|
{} refer to counters and must not be translated. An example would be:
|
|
msgid "Algorithm \\arabic{theorem}"
|
|
msgstr "Algoritmus \\arabic{theorem}"
|
|
|
|
|
|
5) WHAT IS pocheck.pl AND HOW DO I USE IT?
|
|
|
|
This is a small script located in the "po" directory of the source that helps
|
|
you find common errors in your translation. In order to use this script you
|
|
need the script language Perl installed.
|
|
Run ./pocheck.pl -h to see all possible switches.
|
|
|
|
|
|
6) HOW CAN I TEST MY TRANSLATION?
|
|
|
|
In order to test your translation you need to obtain the LyX sources
|
|
(from the git repository) and replace the existing .po with yours.
|
|
Afterwards, you should compile and optionally install LyX (check the
|
|
INSTALL file for your OS). Note that, as of LyX 2.1, it is not
|
|
necessary anymore to install anything.
|
|
|
|
In order to run LyX with your translation, change the current language
|
|
in Preferences dialog or use the appropriate LANG variable:
|
|
|
|
On Linux: LANG=xx_CC lyx
|
|
On Windows, you need to change the lyx.bat file and write: set LANG=xx_CC
|
|
|
|
xx stands for your language code. CC stands for your country code. So to get,
|
|
e.g., Czech, the code is "cs_CZ".
|
|
|
|
Another possibility is to use the Preferences dialog to set LyX UI to
|
|
use your language. Note that, as of LyX 2.2, a newly introduced
|
|
language will not appear in the languages combox unless it corresponds
|
|
to an entry of the lib/languages file that has a "HasGuiSupport true"
|
|
property. See this file for more details.
|
|
|
|
The most comfortable way to see your updated translation while
|
|
editing, is running (in linux) "make xx.gmo" in the po directory to
|
|
compile updated xx.po translation and then run LyX.
|
|
|
|
For advanced users - if you want to remerge your files against current source:
|
|
|
|
- on Linux: execute the command: make update-po
|
|
- on Windows: if you compile LyX in install mode, the po files are automatically
|
|
updated and output to the folder <compilation output folder>\po
|
|
Another option is to build the target "update-po" in MSVC.
|
|
|
|
|
|
7) HOW TO CONTRIBUTE MY WORK?
|
|
|
|
Send your edited xx.po file to po-updates@lyx.org.
|
|
|
|
Also you can check https://www.lyx.org/trac/browser/lyxgit/?rev=master to track
|
|
changes or watch updates.
|
|
|
|
|
|
8) SHALL ALL THE UNUSED STRINGS AT THE BOTTOM OF .PO FILE BE REMOVED,
|
|
OR SHALL THEY STAY?
|
|
|
|
As you wish. They can be reused for generating fuzzy hints when completely
|
|
new strings appear, no other function.
|
|
|
|
|
|
9) CAN YOU EXPLAIN THE "FUZZY" HINT MORE EXPLICITELY?
|
|
|
|
In po files, strings are marked "fuzzy" if the po file generator (the program
|
|
gettext in our case) thinks there is a somewhat sensible translation, but a
|
|
Human translator needs to check and confirm that (by removing the "fuzzy"
|
|
mark). Fuzzy translations are treated as if they were not there, so the
|
|
translation is not used.
|
|
|
|
Fuzzy strings can be auto-generated if a new string is added where gettext
|
|
finds a similar enough translation to suggest a translation.
|
|
|
|
But also if an existing string is changed, its translation is set to "fuzzy"
|
|
(if the original string is similar enough to the previous version).
|
|
|
|
This is often so in the case of accelerators. Accelerators mark the keyboard
|
|
shortcut to access GUI elements. In LyX this is either marked by and ampersand
|
|
(S&earch: shows Search: and has the accelerator Alt+e) or, in menus, by a
|
|
suffix delimited by | (as in Search|e).
|
|
|
|
Since accelerators must be unique in a context, and of course the letter should
|
|
be part of a string, it is the task of translators to decide for an appropriate
|
|
accelerator in their localization. For instance, in German we might have Ma&rke
|
|
for English &Label.
|
|
|
|
As LyX develops, we need to change the accelerators in the English strings in
|
|
many cases to prevent shortcut clashes or adapt strings for coherence. So some
|
|
label "&Foo" is treated as a different (but similar enough) string that was
|
|
previously "F&oo" and hence you need to revisit this string. This makes sense
|
|
as well, as the accelerator in the translation might very welll be adapted to
|
|
the interface changes in your language, too.
|
|
|
|
|
|
10) REFERENCES
|
|
|
|
For a basic idea of how the translation works, you can look at
|
|
|
|
https://en.wikipedia.org/wiki/Gettext
|
|
|
|
For detailed reference (including a full list of country and language codes),
|
|
have a look at
|
|
|
|
https://www.gnu.org/software/gettext/manual/gettext.html
|
|
|
|
|
|
Consider subscribing to the documentation list, lyx-docs@lists.lyx.org (rather
|
|
silent), or the developer's mailing list, lyx-devel@lists.lyx.org (high
|
|
volume).
|
|
|
|
|
|
|
|
PART II - Translation of Math environments and Floats in the final output
|
|
-------------------------------------------------------------------------
|
|
|
|
As of 2.0 LyX allows automatic translation in tex/dvi/ps/pdf output for math
|
|
environment strings (and some floats) which are not automatically translated via
|
|
babel package to the localized form. For example the environment "Exercise"
|
|
becomes "Aufgabe" in the output of the documents with language set to German.
|
|
|
|
These translations are taken from the previously translated .po file before the
|
|
final major LyX release (e.g. 2.0.0) and are fixed for all next minor releases
|
|
(e.g. 2.0.x) in order to have fixed output of LyX documents.
|
|
|
|
The current translation for your language can be found in the file
|
|
lib/layouttranslations. An easy way to check many of the translations is to
|
|
simply load lib/examples/localization_test.lyx in LyX and read its
|
|
instructions.
|
|
|
|
The problematic strings can be then fixed in the .po file. For inspiration the
|
|
typical places in .po files, where to fix the translation, can be seen on the
|
|
following commit: https://www.lyx.org/trac/changeset/38169.
|
|
|
|
If you need to manually regenerate the layouttranslations file from .po files
|
|
- Under Linux: If using autotools, execute the command
|
|
`make ../lib/layouttranslations'
|
|
in the po directory. If using CMake, execute the command
|
|
`make layouttranslations1'
|
|
in the build directory.
|
|
The Python polib library is needed for building the output file.
|
|
- Under Windows:
|
|
1. install the Python extensions "polib". To do this,
|
|
1.1 open a commen line prompt in the folder where you find the file "pip.exe"
|
|
withing the python installation folder.
|
|
1.2 execute the command
|
|
pip install polib
|
|
2. close the command prompt and open the file "lyx.sln" with MSVC. You find
|
|
file in the compilation result folder you set for LyX
|
|
3. right click in MSVC on the target "layouttranslations1" and choose "Rebuild"
|
|
|
|
Optionally - to quickly check whether some new translatable strings appeared
|
|
for your language you can always check ../lib/layouttranslations.review.
|
|
|
|
Q: Running make ../lib/layouttranslations returns with just saying
|
|
../lib/layouttranslations is up to date.
|
|
A: To force regerenation, use something like (XX is your language)
|
|
make -W XX.po ../lib/layouttranslations
|