Difference between revisions of "Translation information"

From Inkscape Wiki
Jump to navigation Jump to search
m (→‎Submit finished work: Add in link to Marc's instructions - working as of Sept. 24)
 
(60 intermediate revisions by 18 users not shown)
Line 1: Line 1:
= Introduction =
This page gathers useful information about translation.
== Community based, user oriented ==
The translations of the various documents focusing on Inkscape rely on the work of volunteers.
Motivation for this work can range from the simple pleasure to contribute to take the opportunity of learning a lot about Inkscape and translation processes.
It is very important not to forget that Inkscape is an open source, community based and user oriented software, which implies that software developpers/contributors are generaly users. It also implies that the translation efforts are also user oriented, with a strong focus on interface, user documentation and website.


== Guidelines/workflow ==
== Links and docs ==


# '''Contact to a local translation group, to get support and help on your language'''. Rather than working alone, you should work with an experienced translation team for your language. Thus you will benefit from their knowledge, as well as being able to communicate with them on your own mother tongue. Moreover, translation teams use to have style guidelines and a standarized vocabulary for technical terms that you should be aware of. There may be many communities working on translations for your own language, but a good starting point is subscribing to your local [http://developer.gnome.org/projects/gtp/teams.html GNOME translation team] or [http://l10n.kde.org/teams/ KDE translation team].
* '''[https://inkscape.org/contribute/translations/ How to contribute in translation]'''
# '''Subscribe to''' [https://lists.sourceforge.net/lists/listinfo/inkscape-translator Inkscape translator mailing list]. By subscribing on Inkscape's translator list you will be able to ask for help on some questions more related to Inkscape issues to other Inkscape translators, as well as the mantainers.
* [https://inkscape.org/doc/devel/translations-statistics-master.html Translations statistics for master branch (development focus)]
# '''Get files for your language'''. If you only want to translate the interface messages, you can get the files from [http://svn.sourceforge.net/viewcvs.cgi/inkscape/ Inkscape's svn repository web interface]. Besides getting files from web interface, you can obtain the full repository; instructions on how to do this are found [http://inkscape.org/svn.php here]. See section [[#Translatable_content]] for which files you have to modify to translate each part of Inkscape.
* [https://inkscape.org/develop/inkscape-git/ Using Inkscape's repositories]
# '''Submit finished work to patch tracker'''. Finished translations must be sent to patch tracker and/or mailing list in order to be integrated into the trunk. You will need a Sourceforge.net account to commit patches to [http://sourceforge.net/tracker/?group_id=93438&atid=604308 Inkscape's patch tracker]. Before sending a file, remember to check that the file(s) you are submitting doesn't have syntax errors that would break the building process.
* [https://lists.inkscape.org/postorius/lists/inkscape-translator.lists.inkscape.org/ Subscribe to the translator mailing list]
# '''Send a mail on the translator mailing list'''. Your contribution will be reviewed/commited as soon as possible.
* [https://lists.inkscape.org/hyperkitty/list/inkscape-translator@lists.inkscape.org/ Translator mailing list archives]
* [https://chat.inkscape.org/channel/team_translation Translator chat channel]
* [[Interface translation]]
* [[Documentation translation]]
* [[WebSite#Translations|Website translation]]


== Best practices ==
== PO translation files ==


* Best case for a good translation : translate from English to your mother tongue.
=== Add a new translation file ===


* Test the behavior of the interface before starting translation.
If the PO file for your language does not exist yet, then you must create it as a copy of the translation template. This template is a file whose name ends with .pot. It contains the strings to translate without any translation. Create a copy and put it to the right place (just see how other languages are managed).


* Several small updates are more efficient than only a big one.
=== Tools for translators ===


* If you're new to Inkscape, or to vector software, taking a look at [[http://wiki.inkscape.org/wiki/index.php/InkscapeTerminology Inkscape Terminology page]] can be a good idea. It is a work in progress, but can give some clues on basic vocabulary of Inkscape.
You can edit PO files from any plain text editor, since they are simple text files. However, many useful tools have been developed to provide a simple experience translating PO files.


* Some good explanations of the behavior of Inkscape, also using some reference terminology can be found here: [[http://tavmjong.free.fr/INKSCAPE/MANUAL/html/index.php A guide to Inkscape]] and [[http://wiki.inkscape.org/wiki/index.php/UserManual User manual]].
Recommended:
* [https://poedit.net/ Poedit] (cross-platform);
* [https://userbase.kde.org/Lokalize Lokalize] (KDE).


== Polishing Translations - Microtypography ==
You might also try:
Here are some things to note in order to achieve good microtypography (typography at the word or character level).
* Emacs's po-mode (contained in the gettext distribution; the version in po-utils is old);
* use the proper quotes (e.g. »foo«)
* [https://wiki.gnome.org/action/show/Apps/Gedit gedit] — text editor for GNOME desktops, has a syntax highlight mode for PO file syntax;
* use the proper kind of dashes (with the proper amount of whitespace around them) - EN DASH (U+2013): "–", MINUS (U+2212): "−"
* [http://virtaal.translatehouse.org/ Virtaal] — cross-platform PO editor that is clean, simple to use yet powerful;
* use non-breakable space where appropriate (e.g. before units; some countries use a halfspace here) - NO-BREAK SPACE (U+00A0): " "
* [https://wiki.gnome.org/Apps/Gtranslator Gtranslator] (GNOME).
* use halfspace where appropriate (example: "z. B.") NARROW No-BREAK SPACE U+202F: " "
* use "24×24", not "24x24"
* use "90°", not "90 degrees" where appropriate
* use the proper Unicode codepoint for "..." - "…"


=== Links ===
And last but not least, [http://www.gnu.org/software/gettext/manual/ gettext] utils, which are installed on every Linux distribution. You can see a complete reference too from installed info pages by running the command:
* http://de.wikipedia.org/wiki/Typografie (German)
<pre>
* [http://www.dante.de/dante/DTK/dtk96_4/Text/dtk96_4_neubauer_feinheiten.pdf  Marion Neubauer: ''Feinheiten bei wissenschaftlichen Publikationen – Mikrotypographie-Regeln, Teil I''] (PDF, German)
info gettext
* [http://www.dante.de/dante/DTK/dtk97_1/Text/dtk97_1_neubauer_feinheiten.pdf  Marion Neubauer: ''Feinheiten bei wissenschaftlichen Publikationen – Mikrotypographie-Regeln, Teil II''] (PDF, German)
</pre>
* [http://www.zvisionwelt.de/typokurz.pdf Christoph Bier: ''typokurz – Einige wichtige typografische Regeln''] (PDF, German)


= Translatable content =
=== Update a translation file ===


Inkscape's translation effort covers many areas, from aplication UI itself to web pages and tutorials. This is a summary of all those areas, sorted by priority.
If a translation file is already present for your language but the programmers have updated the template (.pot) since the translation was done, you need to sync the PO file with the template, especially for the new strings being added, but also for other info: position of the original string in the project, removing or marking obsolete strings, recognizing small string modifications…


These tasks, rather than being for hackers only, can be achieved by most software enthusiasts, whether they have a technological background or were just plain users. The main requirement is the wish to provide support for Inkscape on your language: the technology required for you to do that has been developed in a simple approach, and it involves mainly text files and applications used to verify its syntax. Supporting applications were existing to make these tasks much easier.
Some software offers the ability to automatically sync the translation file with the template, e.g. with Poedit you can use the menu option ‘Catalog > Update from POT file…’.


== User interface ==
GNU gettext also provides the command <code>msgmerge</code>. You can use it like this to update ''lt.po'' from ''inkscape.pot'':
<pre>
msgmerge -U lt.po inkscape.pot
</pre>


PO files contain the strings for the Inkscape user interface (main software and extentions). A PO file is a text file which contains the original English message and its translation. That's why it is obviously the translation to start with.
=== File format ===


See  [[http://wiki.inkscape.org/wiki/index.php/InterfaceTranslation#Interface_Translation InterfaceTranslation]] page for detailed information on the PO files.
If you open a PO file with a text editor for the first time, you will find its syntax very simple. The PO format is a really simple format, which probably at least partly explains its success and widespread use. The format is basically a hash list consisting of msgid and msgstr pairs, with the msgid being the original English string and key, and the msgstr being the translated value of it. Below is an example of a message.


== Tutorials ==
<pre>
#: gedit/dialogs/gedit-plugin-program-location-dialog.c:78
#: gedit/dialogs/program-location-dialog.glade2.h:2
msgid "Set program location..."
msgstr "Ställ in programplats..."
</pre>


As you know, Inkscape comes with some very nice SVG tutorials. By translating them, users will learn how to use the application, as well its tips and tricks.
In addition to the msgid and msgstr parts, a message usually also has lines starting with <code>#:</code> that tell what source files and what lines the string used as msgid was extracted from. These lines have no syntactic value. They are only there as a help for translators and developers to know where a message came from.
It is even a good opportunity for '''you''' to become more acquainted with Inkscape.
 
See [[http://wiki.inkscape.org/wiki/index.php/DocumentationTranslation#Tutorial_Translation Document Translation]] page for detailed information on tutorial translation.


== Keyboard and mouse shortcuts ==
A message in a PO file can be in one of essentially three different states. The message can be translated, fuzzy, or untranslated. A message counts as translated as soon as the msgstr part of it is non-empty. In a similar manner, an untranslated message is one where the msgstr is empty. The fuzzy state is special and essentially means that there is a translation in the msgstr part, but that this translation is most likely not entirely correct, and that it thus needs manual attention by a translator. A message can become fuzzy in one of two ways:


Inkscape is proud for having keyboard and mouse shortcuts for almost any funtionality. Those shotcuts can help you increase your drawing productivity/efficiency. The map of the default shortcuts is embedded in the interface (help menu) next to the tutorials, and can also be accessed from the web site.
* The original string that the msgid represents was changed in the source code. A typo in the string may have been fixed or the string altered in some other way. The translator needs to check that the msgstr is still valid and make changes if necessary.
* A new string has been added to the source, and the string is similar (but not identical) to the msgid of an already existing, translated message. Then the msgstr of that message will be automatically reused for the new message, but the new message will also at the same time be marked fuzzy so that the translator knows there is some difference that he or she needs to adapt the translation to match.


See [[http://wiki.inkscape.org/wiki/index.php/DocumentationTranslation#Keyboard_and_mouse_translation Document Translation]] page for detailed information on translating shortcuts.
=== A few important things to remember ===


== Windows installer ==
* Some strings that can be ambiguous or having several meanings according to different contexts may have a context prefix: ‘Context|Ambiguous string’. In this case, give the translation for ‘Ambiguous string’ only; the ‘Context|’ part is just a not to translate indication.
* After translating a fuzzy string (one that is marked with a <code>", fuzzy"</code> comment), please remove its fuzzy tag — otherwise this translation will be discarded by the build process, meaning that this string will show up untranslated.
* Before publishing your work (after you have finished updating the PO file), please update the <code>"PO-Revision-Date"</code> and <code>"Last-Translator"</code> fields in the PO file header.


High value for users, even if the installation process of Inkscape is quite simple, translating the Windows installer helps potential users a lot to get a good feeling when they use Inkscape.  
If you use a translation software, it may deal with the last two points for you automatically (check the settings).


=== Verification ===


See [[http://wiki.inkscape.org/wiki/index.php/InterfaceTranslation#Windows_installer_translation Interface Translation]] page for detailed information for Windows installer translation.
Before submitting your file to the project, you should make sure it is valid.
* Make sure the file is encoded in UTF-8.
* Make sure it is a valid PO file and obtain some statistics about it: simply run <code>msgfmt --statistics -cv translation_file.po</code> from a command window.
* Make sure it is correctly formatted: run <code>check-markup translation_file.po</code> from a command window and verify it doesn't output any error message. The ‘check-markup’ Perl script can be found in the /po directory of Inkscape trunk.


== Templates ==
If your translation software can compile PO files to .mo, it should detect any errors when you save your translations so you don't need to do any further verifications.


The default template of the Inkscape document can be localized to make the localization consistent. Localized can be the (size?) of the default document and also the name of the default layer.
=== Programmers ===


See [[http://wiki.inkscape.org/wiki/index.php/InterfaceTranslation#Default_template_translation InterfaceTranslation]] page for detailed information on default document's template.
There is always one special message in each valid PO file: the PO file header. It is encoded with the msgid for the empty string (<code>""</code>) as the key, and the actual header values are in the msgstr part. This unfortunately means that if you mark an empty string for translation, you will get the entire PO file header back as the ‘translation’. In almost all cases this is probably not what you want. Hence, do not mark empty strings for translation.


== Man pages ==
Please make sure you use [http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC150 dgettext] for any pluralized strings.
The man pages consist of a standard user documentation, available from the command line. On Unixbased systems simply type "man inkscape" from the prompt of a command window.  


Some distributions also generate a browsable (html) man page, accessible from a dedicated help shortcut.
See also [https://developer.gnome.org/glib/unstable/glib-I18N.html#Q-:CAPS how to disambiguate a string].


The man page of Inkscape provides some insightful information about the software, especially focused on operations that do not require GUI (example: export to png from the command line, or extract one object from a svg file).
== Submit finished work ==


After you translated a file there are three possible means to submit it (the third is preferred as it allows to review the changes easily). These allow to discuss your work and gather relevant information at a dedicated place; they also require you to have an account, please see links below.


See [[http://wiki.inkscape.org/wiki/index.php/DocumentationTranslation#Man_pages DocumentTranslation]] page for detailed information for man page translation.
* Simply send your file to Inkscape's translators mailing list.


== Release notes ==
* Upload your file via the bug tracker for the proper repository: [https://gitlab.com/inkscape/inbox/-/issues Inkscape interface and documentation], [https://gitlab.com/inkscape/inkscape-web-i18n/issues website].<br/>Open a new bug report titled ‘Translation to <your language>’ and attach the files you created or modified to it.
Translating [http://wiki.inkscape.org/wiki/index.php/Release_Notes release notes] helps the "normal user" to get a lot of insight into the capabilities of Inkscape.


- gives a general overview of the possibilities of the software to potential users
* Create a merge request on GitLab ([https://gitlab.com/inkscape/inkscape/ Inkscape interface], [https://gitlab.com/inkscape/inkscape-docs/documentation/ documentation], [https://gitlab.com/inkscape/inkscape-web website]):
*# Visit the repository on GitLab, and click on 'Fork' to create your own, independent repository.
*# Make your changes to the code. There are two possibilities:
*#* Edit the files directly in your repository on the GitLab website via the provided web UI. ''(no prior knowledge required, but please make sure to create a new branch for your work, otherwise this may cause problems for you in the future.)''. Helpful instructions can be found here: https://gitlab.com/inkscape/inkscape/-/merge_requests/6670#note_2102133093.
*#* Download the code to you computer to work with it locally and re-upload it later. ''(some [[Working with Git|Git]] knowledge required)''
*#: Checkout the fork's code to you computer:
*#:: <code>git clone https://gitlab.com/<your_username>/<repository-name></code>
*#: Replace the previous file for your language with your new file in the directory. If there is no previous file, put your file into the right place. Tell the system it must take care of your added/changed file with:
*#:: <code>git add /path/to/your-file.po</code>
*#: Commit your changes to your own repository (put the correct information instead of the <placeholders>):
*#:: <code>git commit -m "Translated <file> for <language>, <xx>% complete</code>
*#:: <code>git push</code>
*# Visit your repository on the GitLab website, go to 'Merge requests' and make a new merge request, asking for your work to be reviewed and included in the correct branch, as well as also to forward port the changes to the master branch. Make sure to enable the boxes to 'allow edits by maintainers' and to 'squash commits'.


- can be used for local marketing (local Free Software/Linuw/Graphics oriented web sites, articles in fanzines, e-magazines and even magazines...)
Many thanks for your work!


== Review ==


See [[http://wiki.inkscape.org/wiki/index.php/WebSiteTranslation#Release_notes WebSiteTranslation]] page for detailed information on translating release notes.
This is the start of a list of places to get translation reviews done. So far:
* http://www.linux.it/tp/


== User manual ==
[[Category:Translation]]
Some members of the Inkscape community are also focusing on an [[http://wiki.inkscape.org/wiki/index.php/UserManual user manual]]. This document can be read as a reference document for advanced users and as a good introduction to the functionalities of Inkscape by everyone.
 
See [[http://wiki.inkscape.org/wiki/index.php/DocumentationTranslation#User_Manual DocumentTranslation]] page for detailed information on translating the user manual.
 
== Web pages, News and Wiki ==
English is generaly the exchange-tongue of developppers, and developper/user documentation is mainly written in English.
 
Translation efforts should be first oriented on user documentation.
 
You can take a look at the [[http://wiki.inkscape.org/wiki/index.php/WebSiteTranslation WebSiteTranslation]] page for detailed information about how to translate the web content of Inkscape
 
See [[http://wiki.inkscape.org/wiki/index.php/WebSiteTranslation WebSiteTranslation]] page for detailed information on translating the web site, news and wiki.
 
See the [[http://wiki.inkscape.org/wiki/index.php/Main_Page main wiki page of Inkscape]] to get some examples (Spanish and German) of the translation of this wiki.
 
== Others ==
Text files found in the inkscape directory
...
 
= Status =
See this [[http://wiki.inkscape.org/wiki/index.php/TranslationStatus dedicated page]]

Latest revision as of 13:27, 12 September 2024

This page gathers useful information about translation.

Links and docs

PO translation files

Add a new translation file

If the PO file for your language does not exist yet, then you must create it as a copy of the translation template. This template is a file whose name ends with .pot. It contains the strings to translate without any translation. Create a copy and put it to the right place (just see how other languages are managed).

Tools for translators

You can edit PO files from any plain text editor, since they are simple text files. However, many useful tools have been developed to provide a simple experience translating PO files.

Recommended:

You might also try:

  • Emacs's po-mode (contained in the gettext distribution; the version in po-utils is old);
  • gedit — text editor for GNOME desktops, has a syntax highlight mode for PO file syntax;
  • Virtaal — cross-platform PO editor that is clean, simple to use yet powerful;
  • Gtranslator (GNOME).

And last but not least, gettext utils, which are installed on every Linux distribution. You can see a complete reference too from installed info pages by running the command:

info gettext

Update a translation file

If a translation file is already present for your language but the programmers have updated the template (.pot) since the translation was done, you need to sync the PO file with the template, especially for the new strings being added, but also for other info: position of the original string in the project, removing or marking obsolete strings, recognizing small string modifications…

Some software offers the ability to automatically sync the translation file with the template, e.g. with Poedit you can use the menu option ‘Catalog > Update from POT file…’.

GNU gettext also provides the command msgmerge. You can use it like this to update lt.po from inkscape.pot:

msgmerge -U lt.po inkscape.pot

File format

If you open a PO file with a text editor for the first time, you will find its syntax very simple. The PO format is a really simple format, which probably at least partly explains its success and widespread use. The format is basically a hash list consisting of msgid and msgstr pairs, with the msgid being the original English string and key, and the msgstr being the translated value of it. Below is an example of a message.

#: gedit/dialogs/gedit-plugin-program-location-dialog.c:78
#: gedit/dialogs/program-location-dialog.glade2.h:2
msgid "Set program location..."
msgstr "Ställ in programplats..."

In addition to the msgid and msgstr parts, a message usually also has lines starting with #: that tell what source files and what lines the string used as msgid was extracted from. These lines have no syntactic value. They are only there as a help for translators and developers to know where a message came from.

A message in a PO file can be in one of essentially three different states. The message can be translated, fuzzy, or untranslated. A message counts as translated as soon as the msgstr part of it is non-empty. In a similar manner, an untranslated message is one where the msgstr is empty. The fuzzy state is special and essentially means that there is a translation in the msgstr part, but that this translation is most likely not entirely correct, and that it thus needs manual attention by a translator. A message can become fuzzy in one of two ways:

  • The original string that the msgid represents was changed in the source code. A typo in the string may have been fixed or the string altered in some other way. The translator needs to check that the msgstr is still valid and make changes if necessary.
  • A new string has been added to the source, and the string is similar (but not identical) to the msgid of an already existing, translated message. Then the msgstr of that message will be automatically reused for the new message, but the new message will also at the same time be marked fuzzy so that the translator knows there is some difference that he or she needs to adapt the translation to match.

A few important things to remember

  • Some strings that can be ambiguous or having several meanings according to different contexts may have a context prefix: ‘Context|Ambiguous string’. In this case, give the translation for ‘Ambiguous string’ only; the ‘Context|’ part is just a not to translate indication.
  • After translating a fuzzy string (one that is marked with a ", fuzzy" comment), please remove its fuzzy tag — otherwise this translation will be discarded by the build process, meaning that this string will show up untranslated.
  • Before publishing your work (after you have finished updating the PO file), please update the "PO-Revision-Date" and "Last-Translator" fields in the PO file header.

If you use a translation software, it may deal with the last two points for you automatically (check the settings).

Verification

Before submitting your file to the project, you should make sure it is valid.

  • Make sure the file is encoded in UTF-8.
  • Make sure it is a valid PO file and obtain some statistics about it: simply run msgfmt --statistics -cv translation_file.po from a command window.
  • Make sure it is correctly formatted: run check-markup translation_file.po from a command window and verify it doesn't output any error message. The ‘check-markup’ Perl script can be found in the /po directory of Inkscape trunk.

If your translation software can compile PO files to .mo, it should detect any errors when you save your translations so you don't need to do any further verifications.

Programmers

There is always one special message in each valid PO file: the PO file header. It is encoded with the msgid for the empty string ("") as the key, and the actual header values are in the msgstr part. This unfortunately means that if you mark an empty string for translation, you will get the entire PO file header back as the ‘translation’. In almost all cases this is probably not what you want. Hence, do not mark empty strings for translation.

Please make sure you use dgettext for any pluralized strings.

See also how to disambiguate a string.

Submit finished work

After you translated a file there are three possible means to submit it (the third is preferred as it allows to review the changes easily). These allow to discuss your work and gather relevant information at a dedicated place; they also require you to have an account, please see links below.

  • Simply send your file to Inkscape's translators mailing list.
  • Upload your file via the bug tracker for the proper repository: Inkscape interface and documentation, website.
    Open a new bug report titled ‘Translation to <your language>’ and attach the files you created or modified to it.
  • Create a merge request on GitLab (Inkscape interface, documentation, website):
    1. Visit the repository on GitLab, and click on 'Fork' to create your own, independent repository.
    2. Make your changes to the code. There are two possibilities:
      • Edit the files directly in your repository on the GitLab website via the provided web UI. (no prior knowledge required, but please make sure to create a new branch for your work, otherwise this may cause problems for you in the future.). Helpful instructions can be found here: https://gitlab.com/inkscape/inkscape/-/merge_requests/6670#note_2102133093.
      • Download the code to you computer to work with it locally and re-upload it later. (some Git knowledge required)
      Checkout the fork's code to you computer:
      git clone https://gitlab.com/<your_username>/<repository-name>
      Replace the previous file for your language with your new file in the directory. If there is no previous file, put your file into the right place. Tell the system it must take care of your added/changed file with:
      git add /path/to/your-file.po
      Commit your changes to your own repository (put the correct information instead of the <placeholders>):
      git commit -m "Translated <file> for <language>, <xx>% complete
      git push
    3. Visit your repository on the GitLab website, go to 'Merge requests' and make a new merge request, asking for your work to be reviewed and included in the correct branch, as well as also to forward port the changes to the master branch. Make sure to enable the boxes to 'allow edits by maintainers' and to 'squash commits'.

Many thanks for your work!

Review

This is the start of a list of places to get translation reviews done. So far: