Difference between revisions of "Translation"
From GnuCash
m (→Translating the GnuCash Guide and Manual: -> Manual and Guide) |
|||
| (716 intermediate revisions by 36 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | [[Category:Translation]] | |
| + | {| class="wikitable" style="margin: auto;" | ||
| + | ! scope="row"|Languages | ||
| + | | [[Zh-hans/翻译|简体中文]] | ||
| + | | | [[He/{{PAGENAME:תרגום}}|עִברִית]] | ||
| + | |} | ||
| − | -- | + | ;Tip: Use [https://translate.google.com/translate?hl=en&sl=en&tl=de&u=https%3A%2F%2Fwiki.gnucash.org%2Fwiki%2FTranslation&sandbox=1 Google translation] and select your language to get a machine translation of this document. |
| + | The concept of this document is to give you step-by-step instructions on how to create or update ''translation''s and other ''localization'' tasks for the gnucash project. | ||
| − | + | There are related pages for | |
| − | + | :programmers: [[I18N]] and | |
| − | + | :project maintainers: [[Language_Administration]]. | |
| − | + | == Overview == | |
| − | |||
| − | |||
| − | + | GnuCash has several separate areas that need translations or localization, which are by priority: | |
| − | + | ;The [[#The glossary file|Glossary]]: A reference in form of a ''message catalog'' with terms that are commonly used throughout GnuCash's other components and their '''explanation'''. Preferably it should be translated first for each new language to define a consistent terminology for the other parts. | |
| − | + | :[{{URL:wl|engage}} {{URL:wl|widgets}}-/glossary/287x66-grey.png] | |
| + | ;The [[#Translating the Program|Program]]: Its ''message catalogs'' contain all text messages for the application's user interface. Not all are equally important though. | ||
| + | :[{{URL:wl|engage}} {{URL:wl|widgets}}-/gnucash/287x66-grey.png] | ||
| + | :Please read at least [[#Adjust special messages]] and [[#Special characters and other tips]], if you use one of that services. | ||
| + | ;The [[Windows Installer Translation|Windows Installer]]: It contains some '''20''' strings. | ||
| + | ;The [[#How to translate the files containing the new account hierarchies|Account Templates]]: A set of ready to use account chart snippets ''for personal users'' that can be mixed and matched into a full chart of accounts during the creation of a new a new GnuCash file with currently '''115''' translatable account names. | ||
| + | :*If your government or other authorities offer specific templates ''for business users'', you can create them, too. | ||
| + | ;The [[#Translating the GnuCash Guide and Help|Documentation]]: The Help Manual and the [[Concept Guide|Tutorial and Concepts Guide]]. These documents explain how to use GnuCash. They are written in DocBook, an XML variant. | ||
| + | ;The [[#How to translate the website|Website]]: While mostly written in PHP/HTML, it uses ''message catalogs'', too. | ||
| + | :[{{URL:wl|engage}} {{URL:wl|widgets}}-/website/287x66-grey.png] | ||
| + | :* In theory one could also translate recent announcements from the '''news''' directory into the language specific subfolder, but ususally there are more important tasks around. | ||
| + | ;The [[#How to create localized Income Tax Tables|Income Tax Tables]]: They require some knowledge of your regional tax rules and are related to ''account templates''. | ||
| + | ;Currencies: GnuCash uses the translation of the ISO 4217 '''currency''' codes and names. This are maintained by the [https://salsa.debian.org/iso-codes-team/iso-codes ISO Codes Team]. If your language is missing or has issues contact them or contribute: | ||
| + | :[{{URL:wl|engage|iso-codes}} {{URL:wl|widgets|iso-codes}}-/iso-4217/287x66-white.png] | ||
| + | * Optionally you can [[#Check Files in Repo gnucash's doc Directory]] files, too. | ||
| − | == | + | == Available Resources == |
| + | There are many resources to support you at gnucash.org and other places. Don't hesitate to use them. | ||
| − | + | === gnucash.org === | |
| − | use | + | We have collected a bunch of useful information for you here in '''this wiki''' - |
| − | + | :''navigate'' from the [[GnuCash|main page]], or the [[Special:Categories]] or use the ''search'' function - | |
| − | + | and on the '''website''' {{URL:www}}. | |
| − | + | And we have several '''channels of communication''' and a few other useful tools: | |
| − | and | + | :;IRC: The fastest way to get help on ''simple questions'' is using the '''internet relay chat''' [[IRC]], as many of the developers hang out there and are eager to help. |
| − | + | :;Mailing lists: Translators will probably find two or three gnucash mailing lists of interest. If you can not find the answers to your questions in their [[Mailing_Lists#Mailing List Archives]], feel free to ask them. | |
| + | ::* For ''language and region specific questions'', where you should discuss terms and ask for proofreading of your work, use your languages mailing list. Currently we have | ||
| + | ::*: '''gnucash-'''[pt_]'''br''',''' de''',''' es''',''' fr''',''' it''',''' nl'''. | ||
| + | ::: If none exists for your language or nobody has an answer there, use the english lists: | ||
| + | :::* ''General use questions'' and answers are found on the '''gnucash-users''' mailing list, | ||
| + | :::* specific ''development questions'' go to the '''gnucash-devel''' list. | ||
| + | ::* If you dislike the heavy traffic on the above lists, you should at least subscribe the [{{ListURL}}/mailman/listinfo/gnucash-announce gnucash-announce] list to get informed about new :releases. | ||
| + | :To ''subscribe'' or ''view archives'' of these lists follow the links to the [[Mailing Lists]]. | ||
| − | + | === weblate.org === | |
| − | + | Since 2020-12-14 the translations of some components, currently ''Glossary'', ''Program'' and ''Website'', are available at [{{URL:wl}} GnuCash @ Hosted Weblate]. | |
| + | ;Requirement: Only a ''web browser'' on your PC or mobile. | ||
| + | ;Features: | ||
| + | * Most pages of weblate have a help page behind the <code>?</code> button. | ||
| + | * Already as '''anonymous''' you can add ''suggestions'' and ''comments''. | ||
| + | * After you created there an '''account''', you can edit the translations. | ||
| + | *;Tip: If you also have a [{{URL:GH}} GitHub] account and linked it there, we can give you some feedback on your contributions. | ||
| + | * If you already have been a '''GnuCash translator''', tell us | ||
| + | *: on {{IRC-URL}} ([[IRC|help about IRC]]) or | ||
| + | *: by a mail to the gnucash-devel list your Weblate name to become a weblate/GnuCash reviewer there. | ||
| + | ;Note: We appreciate any help on the optimal configuration by '''experienced weblate users'''. You can contact the GnuCash team by {{IRC-URL}} or [[Mailing Lists]]. | ||
| − | + | ==== Other Web Based Translation Tools ==== | |
| − | + | Several services for translation coordination exist, see [[Improve Localization Process#Web Based Translation Tools]]. As we have no experience with them contact the gnucash-devel mailing list before using them. | |
| − | The | + | === translationproject.org === |
| − | + | The [{{URL:TP}} Translation Project] coordinates the ''message cataloges'' of several '''programs''' | |
| + | ;Up to Gnucash 4.9 (2021-12): some of our translators had used it: [{{URL:TP}}obsolete/gnucash/?C=M;O=D last files]. Most of them are now using Weblate. | ||
| − | == | + | === Classical Direct Contribution === |
| + | If you want to work on a new translation and you want to submit it directly to GnuCash, read on. | ||
| − | + | If you're starting a new translation it's much easier to begin with a tarball, which will include <tt>po/gnucash.pot</tt>; if you start from a [[Git]] clone you'll have to [[Building|build]] Gnucash yourself first to generate <tt>gnucash.pot</tt>. | |
| − | [[ | ||
| − | + | === On Other Sites === | |
| − | + | ;Technical Reference: For many components we use the '''Gettext''' package. If you need help with <tt>msg*</tt> commands or the .po file format, read it's [{{URL:gettext-manual}} manual]. | |
| − | + | ;General Translations Guidelines and Tips: General information about how to approach the translation of software can be found here: | |
| − | + | :;Weblate: | |
| − | + | ::* {{URL:wl doc}} | |
| + | :;Gnome: As GnuCash is [[GTK]] based we follow their rules for consistency. | ||
| + | ::* In [{{URL:Gnome-HIG}} GNOME Human Interface Guidelines] the most important section is ''writing-style'', but also ''keyboard-input'' is of interest for the program. | ||
| + | ::* [{{URL:Gnome-old-sg}} GNOME Documentation Style Guide V1.6] | ||
| + | ::* {{URL:GTP}} | ||
| + | ::* {{URL:GTP}}/LocalisationGuide | ||
| + | :;KDE: | ||
| + | ::* [https://l10n.kde.org/docs/translation-howto/index.html The KDE Translation HOWTO] | ||
| − | + | ;Other Useful Sites: | |
| − | + | :* Often, but not always, {{URL:wp}} has a good explanation and proper language links for special terms. | |
| − | + | :: Comparing articles on wikipedia in your language and english can be helpful. | |
| + | :* There are many online dictionaries, use a search engine like google, to find the best fitting. | ||
| + | :* An index of on-line dictionaries and a lot of other resources can be found at www.yourdictionary.com. | ||
| + | :* In special cases the terminology database of the European Union [https://iate.europa.eu/info/documentation Inter Active Terminology for Europe] can be used, too. | ||
| − | + | == How to submit changes directly to GnuCash == | |
| − | + | There are several options to contribute to the GnuCash translations: | |
| − | + | ===Weblate=== | |
| − | and | + | We recommend to use Weblate for existing languages as it has additional checks and other nice features compared to the pure gettext tools. |
| − | + | ;Online: ''One hour after you stopped editing'' it will create a commit on your behalf in its current pull request. | |
| + | ;Offline: If you want to work offline, you can download the po file, edit it with your preferred editor, and upload it again. Weblate will then format it in the referred way before commiting it to its current pull request. | ||
| + | ;Tip: If you have a GitHub account linked to your weblate account you will get informed and can follow the process. | ||
| − | + | === Pull Requests at GitHub === | |
| − | + | Pull requests are common for all parts which are not covered by weblate. | |
| − | After | + | If you already are a [{{URL:GH}} github] user you can publish your work as a separate branch on your gnucash[-{[ht]docs|on-windows}] fork and send a pull request to the GnuCash team. If you wish to continue your work before the request was completed, simlply create a new working branch. After the pull request was completed you can delete the related branch again. See [[Git]] for details. |
| − | + | ;Commit messages: | |
| + | :# Start your commit message with <tt>L10N:<LL>: </tt> | ||
| + | :#: were <LL>—or ${LL} below—is your language code. | ||
| + | :# Append the intended improvement | ||
| + | :;Example: <tt>L10N:de: Update of SKR49 to official 2023 release</tt> | ||
| − | == | + | ===Verify the Result=== |
| + | After it got merged, you can … | ||
| + | :;Website: immediately open {{{URL:www}} | ||
| + | :;Program: the next day download the (Linux) [[Flatpak#Nightly_Test_Versions_at_gnucash.org|Flatpak]] or [[Windows#Q:_Are_there_nightly_builds.3F|Windows]] nightly | ||
| + | to see and test the reslut of your work. | ||
| − | + | === Obsolete Ways === | |
| − | + | Use they only if you have good reasons not to use one of the ways mentioned before! | |
| − | |||
| − | |||
| − | + | ==== Patches at Bugzilla ==== | |
| + | Before it was recommend to use [[Bugzilla]]. : | ||
| + | * [{{BugURL}}/createaccount.cgi Create an account] if you still have none or [{{BugURL}}/index.cgi?GoAheadAndLogIn=1 login], | ||
| + | * [{{BugURL}}/enter_bug.cgi?product=GnuCash&component=Translations&bug_severity=enhancement create an ''request for enhancement'' bug against the Gnucash ''component translations''], choose the version on which your patch is based and | ||
| + | * attach a patch | ||
| + | :containing the diff between the old files - if any - and your new files: | ||
| + | :* If you have [[Git]] installed, the easiest way to create the patch is <syntaxhighlight lang="sh" inline>git format-patch origin/stable..stable</syntaxhighlight>. | ||
| + | :* Else you can use ''diffutils'': <syntaxhighlight lang="sh" inline>diff -u[r] <original path> <modified path> > <name>.patch</syntaxhighlight>. See <syntaxhighlight lang="sh" inline>info diff</syntaxhighlight> for details. | ||
| − | + | ==== Mailing lists ==== | |
| + | You can simply email your completed message catalog (<tt>.po</tt> file) to the developers at the [mailto:gnucash-devel@gnucash.org gnucash-devel] mailing list. We'd really rather you use Github or Bugzilla because those are much less likely to get lost or forgotten, but if you really find those too hard we'll try to accommodate you on the list. | ||
| − | + | == Translating the Program == | |
| − | + | To begin a translation you need either the message template file (gnucash.pot) if you're starting a new translation or the existing message catalog (xx.po or xx_YY.po, where xx is the ISO code for your language and YY the ISO code for a language-variant locale, see [[#Naming Convention|Naming Convention]]). These files are in the gnucash sources, which you can obtain either from our [{{URL:GH}}gnucash.git git repository] or by downloading the latest '''release''' tarball from [https://www.sourceforge.net/projects/gnucash/files/gnucash%020(stable) Sourceforge]. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | === Get the source from Git === | |
| − | + | GnuCash uses [[Git]] as version control system. If it is new for you read [[An Introduction to Git]]. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | The first thing to do is ''usually'', to download the latest <tt>stable</tt> branch of gnucash from git and get it to build.{{Git branchs rename.ref}} | |
| − | + | Normally checkout the current stable branch: <Syntaxhighlight lang="sh"> | |
| − | + | git clone https://github.com/Gnucash/gnucash ${SOURCEDIR} | |
| − | + | cd ${SOURCEDIR} | |
| − | + | git checkout stable | |
| − | + | </Syntaxhighlight> | |
| − | + | The argument '''${SOURCEDIR}''' above can be whatever you want your local directory to be called, | |
| − | + | and is optional in the first line. If you leave it out, you'll have a directory called <tt>gnucash</tt> created | |
| − | + | containing all the source code ''below your current working dir''. | |
| − | |||
| − | |||
| − | |||
| − | + | Checkout the documentation (optional, but recommended): <Syntaxhighlight lang="sh"> | |
| − | + | git clone https://github.com/Gnucash/gnucash-docs gnucash-docs | |
| + | cd gnucash-docs | ||
| + | git checkout stable | ||
| + | </Syntaxhighlight> | ||
| − | + | ==== Update your repository ==== | |
| − | + | After this initial git checkout, you can later update your local repository using <Syntaxhighlight lang="sh"> | |
| − | + | git pull --rebase | |
| − | + | </Syntaxhighlight> | |
| − | + | from anywhere in the tree of ${SOURCEDIR}. We recommend to do it daily when you start your work. | |
| − | + | === Get packages, which are used while building === | |
| − | + | * [[Dependencies]] contains the list of packages, which are used while building GnuCash. If some are missing the configuration by <tt>cmake</tt> or the build by <tt>make</tt> or <tt>ninja</tt> will fail. | |
| − | + | * For working on .po files we use several commands starting with <tt>msg</tt>. This are part of '''gettext-tools'''. | |
| + | :;Caution: Gettext versions < 0.20 are known not to extract the 'developer_name' xml node, which contains the msgid "GnuCash Project". Do not remove this msgid! | ||
| + | *;Optional: [{{URL:wp}}Translate_Toolkit Translate Toolkit] is already used by Weblate and other projects. While ''gettext'' offers only a few ''formal checks'' '''Translate Toolkit''' has many ''quality checks'' in its <tt>pofilter</tt> command. | ||
| + | Under Linux use your package manager and install them. | ||
| − | + | === Steps in the Build System === | |
| − | + | GnuCash uses the [https://cmake.org cmake] build generator to control the build of all components. Details are described in [[Building]]. The following short-form instructions work on Unix systems and assume that you have already set up the dependencies according to [[FAQ#Q:_I_heard_it_is_too_hard_to_compile_GnuCash.21|the FAQ]]. If you are building the unstable or master branches you'll need to use your package manager to install two more development packages, boost-all-devel and googletest. | |
| − | |||
| − | |||
| − | + | ==== Build system generation ==== | |
| + | It's generally preferred to use a separate build directory. So let's set one up next to our source directory:<SyntaxHighlight lang="sh"> | ||
| + | cd /path/to/gnucash # replace the example path with your real source path | ||
| + | mkdir ../gnucash-build | ||
| + | cd ../gnucash-build | ||
| + | </SyntaxHighlight> | ||
| − | + | Next generate a build system in the build directory. Still in the build system, exectue<SyntaxHighlight lang="sh"> | |
| + | cmake -D CMAKE_INSTALL_PREFIX=../gnucash-install ../gnucash | ||
| + | </SyntaxHighlight> | ||
| − | + | This will set up a proper build system in the build directory based on the CMakeLists.txt file in the source directory. If generation fails or if you want to refine your build consult [[Building]]. | |
| − | + | If all goes well you'll end up with a directory structure as follows:<SyntaxHighlight lang="sh"> | |
| + | path/to/ | ||
| + | gnucash/ # directory with gnucash sources | ||
| + | gnucash-build/ # directory to build gnucash and its translation in | ||
| + | gnucash-install/ # directory to install final result (not needed for development, just for completeness) | ||
| + | </SyntaxHighlight> | ||
| − | + | ==== Compile ==== | |
| − | + | It is recommended that you compile the gnucash source code. It is a good idea to actually run gnucash with your new translations because it is quite helpful to see the phrases in the context of the running program. | |
| − | + | Compilation is done by executing the ''make'' command in the ''build directory''. | |
| − | |||
| − | + | ;Note: Experienced users may prefer to use [[Build_Tools#Ninja|Ninja]] instead of [[Build_Tools#Make|Make]]. How to so is beyond the scope of this page. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | = | + | <Syntaxhighlight lang="sh"> |
| + | cd ${BUILDDIR} # e.g. path/to/gnucash-build/ | ||
| + | make | ||
| + | </Syntaxhighlight> | ||
| − | + | ==== Run ==== | |
| − | + | GnuCash can be run from the ''build directory'' as follows: <Syntaxhighlight lang="sh"> | |
| + | cd ${BUILDDIR} # e.g. path/to/gnucash-build/ | ||
| + | ./bin/gnucash # will open gnucash you just built | ||
| + | </Syntaxhighlight> | ||
| − | + | Note the use of './bin/' in the line to execute gnucash. This is to make sure you run | |
| + | the gnucash executable you just built rather than one that's installed by your distribution. | ||
| + | Omitting this explicit path specification in the command will cause your system to launch | ||
| + | your distribution's pre-installed version of gnucash:<Syntaxhighlight lang="sh"> | ||
| + | gnucash # will open your distribution's pre-installed gnucash | ||
| + | </Syntaxhighlight> | ||
| + | <!--FIXME: Other OSes--> | ||
| + | |||
| + | In either case, you can easily switch between the various languages the | ||
| + | gnucash has available by placing the LANG env var before the call to the | ||
| + | executable. You can find details in [[Locale Settings]]. | ||
| − | + | ==== Documentation ==== | |
| − | the | + | The ''GnuCash Help Manual'' and the ''Tutorial and Concepts Guide'' can use the same [[CMake]] build system as the code. |
| − | |||
| − | + | # <syntaxhighlight lang="sh" inline>git clone gnucash-docs</syntaxhighlight> or unpack a gnucash-docs tarball | |
| + | # Using a terminal, go to your gnucash-docs directory <SyntaxHighlight lang="sh"> | ||
| + | cd /path/to/gnucash-docs # replace the example path with your real path | ||
| + | </SyntaxHighlight> | ||
| + | # Make a build directory next to your source directory and go into it <SyntaxHighlight lang="sh"> | ||
| + | mkdir ../gnucash-docs-build | ||
| + | cd ../gnucash-docs-build | ||
| + | </SyntaxHighlight> | ||
| + | # Configure the build system<SyntaxHighlight lang="sh"> | ||
| + | cmake -D CMAKE_INSTALL_PREFIX=../gnucash-docs-install ../gnucash-docs | ||
| + | </SyntaxHighlight> | ||
| + | #: These commands will set up a directory structure as follows:<SyntaxHighlight lang="sh"> | ||
| + | path/to/ | ||
| + | gnucash-docs/ # directory with gnucash-docs sources | ||
| + | gnucash-docs-build/ # directory to generate gnucash-docs in various formats | ||
| + | gnucash-docs-install/ # directory to install final result (not needed for development, just for completeness) | ||
| + | </SyntaxHighlight> | ||
| + | # still in your build directory run <Syntaxhighlight lang="sh"> | ||
| + | make html | ||
| + | </Syntaxhighlight> | ||
| − | + | The new documentation home pages will be <syntaxhighlight lang="sh">${BUILDDIR}/share/doc/${LOCALE}/gnucash-guide/index.html</syntaxhighlight> and <syntaxhighlight lang="sh">${BUILDDIR}/share/doc/${LOCALE}/gnucash-manual/index.html</syntaxhighlight>, | |
| − | + | where ${LOCALE} is one of <tt>C, de, it, ja, or pt</tt> (English, German, Italian, Japanese, or Portuguese respectively). You can use the <tt>file:</tt> URL scheme to point your browser to one of them; the links will work from there. | |
| − | |||
| − | + | === Naming Convention === | |
| + | The language code is of the following form: | ||
| + | :;<language>[_<REGION>][.<Charset>][@modifier]:using the well known ISO codes [{{URL:wp}}List_of_ISO_639-1_codes 639-1] for '''language'''s and [{{URL:wp}}ISO_3166-1 3166-1] for '''region'''s, which are in most cases countries . | ||
| + | :* Only ''if no 2 letter code exists'' for your language in ISO_639-1, use the 3 letter code from [{{URL:wp}}List_of_ISO_639-2_codes ISO_639-2]. | ||
| + | * If you are the first translator for your language, you should | ||
| + | ** name your files and directories ''only with your language code''. | ||
| + | ** set <tt>Language:</tt> in the header of your po file with the full (language and region) code, if significant. | ||
| + | : So all people using your language despite of their region will benefit from your work. | ||
| + | * If there are parts, which are ''specific for your region'', e.g. business account templates respecting local law, then they should be in a <language>_<REGION> directory. | ||
| + | * The common '''charset''' in gnucash is [{{URL:wp}}Utf8 utf8]. | ||
| + | * In the rare case ''different scripts'' are used for the same language like kyrilic and latin add for the less used the '''modifier''' e.g. <tt>sr@latin</tt>. | ||
| − | + | In the following parts of this document 'XXXX' and 'LL'—often prefixed by <tt>$</tt> to mark them as variable—refer to your language code. | |
| + | === The glossary file === | ||
Inside the po/glossary/ directory should be a "glossary" file for your | Inside the po/glossary/ directory should be a "glossary" file for your | ||
| − | language. This file contains a bunch of commonly used terms found in | + | language. This file contains a bunch of ''commonly used terms'' found in GnuCash - and the explanation of a few very specific for GnuCash like the disambiguation between ''bill'', ''invoice'' and ''voucher''. |
| − | It is recommended that you get this file translated first, and use it as a | + | It is recommended that you '''get this file translated first''', and use it as a |
| − | guide when translating the real .po file. | + | guide when translating the real .po file or the documentation. Please keep in mind that this file will ''never be visible to a user''! The glossary file is only a tool for you, the translators! I repeat: The strings from the glossary file will ''never'' be user-visible, they are only used by you, the translator. |
| − | + | ::;Todo: The current files have a very informal form. To make them more useful like conversion in tool specific glossary formats, we should replace <syntaxhighlight lang="po"> | |
| + | msgid "generic term: term" | ||
| + | </syntaxhighlight> by <syntaxhighlight lang="po"> | ||
| + | msgctxt "generic term" | ||
| + | msgid "term" | ||
| + | </syntaxhighlight> | ||
| − | + | # Go into the glossary directory: <Syntaxhighlight lang="sh"> | |
| − | + | cd po/glossary/ | |
| + | </Syntaxhighlight> | ||
| + | # If your .po glossary file ''does not exist'' or ''is older than'' <tt>gnc-glossary.txt</tt>, create the template: <Syntaxhighlight lang="sh"> | ||
| + | ./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot | ||
| + | </Syntaxhighlight> | ||
| + | # Create or update your language's glossary file: | ||
| + | #* If your .po glossary file ''does not exist'', | ||
| + | ## use this gnc-glossary.pot file to create it with <Syntaxhighlight lang="sh"> | ||
| + | msginit # add -l<locale> if different from your settings | ||
| + | </Syntaxhighlight> | ||
| + | ## Add your file into the <tt>set_dist_list(po_glossary_DIST ...)</tt> command in <tt>glossary/CMakeLists.txt</tt> <Syntaxhighlight lang="cmake"> | ||
| + | set_dist_list(po_glossary_DIST CMakeLists.txt bg.po ca.po da.po de.po el.po es_NI-policy.txt es.po fr.po gnc-glossary.txt he.po | ||
| + | hr.po hu.po it.po nb.po nl.po pl.po pt_BR.po pt.po ru.po rw.po sk.po sv.po txt-to-pot.sh vi.po zh_CN.po zh_TW.po) | ||
| + | </Syntaxhighlight> to get it into the tarball. | ||
| + | ## After changing CMakeLists.txt you have to rerun <Syntaxhighlight lang="sh"> | ||
| + | cmake # add your options | ||
| + | </Syntaxhighlight> | ||
| + | #* If your .po glossary file ''exists'', but is older than <tt>gnc-glossary.txt</tt> use the msgmerge program to update it: <Syntaxhighlight lang="sh"> | ||
| + | msgmerge --previous -U $LL.po gnc-glossary.pot; | ||
| + | </Syntaxhighlight> | ||
| + | # Now open your language's glossary file and translate it completely. | ||
| + | # Don't forget to [[#Check syntax and statistics of your .po file]]. | ||
| − | If your .po glossary file | + | ==== Terms missing or inadequate in the glossary file ==== |
| − | + | If you detect an important term which is missing or could be better explained, | |
| + | * create a pull request at github | ||
| + | : for the ''source file'' '''gnc-glossary.txt'''. | ||
| + | With the exception of the header the lines of this file are alphabetical sorted and have the form: <Syntaxhighlight lang="text"> | ||
| + | Msgid<TAB>Comment | ||
| + | </Syntaxhighlight> | ||
| + | :;Reminder: Does your editor enter <TAB>s or will it replace them with <Space>s? | ||
| + | To test it, run the following steps after you changed gnc-glossary.txt: | ||
| + | # To generate a new gnc-glossary.pot: <Syntaxhighlight lang="sh"> | ||
| + | ./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot</Syntaxhighlight> | ||
| + | # run above ''msgmerge'' command for your LL.po, | ||
| + | # check and translate the new string in this updated glossary file. | ||
| + | # If successful, update all *.po files with: <Syntaxhighlight lang="sh"> | ||
| + | for i in *.po; do echo -n "$i:"; LANG=C msgmerge --previous -U $i gnc-glossary.pot ; done | ||
| + | #old form: find *.po -exec /usr/bin/msgmerge --previous -U '{}' gnc-glossary.pot \; | ||
| + | </Syntaxhighlight> | ||
| + | ;Note: The last step can also be done by a maintainer. | ||
| + | :<tt>LANG=C</tt> is only recommend for maintainers to get english error messages. | ||
| − | + | === Get a fresh template === | |
| + | The ''Portable Object Template'' (.pot file) is a collection of all translatable strings. | ||
| − | + | It is important, to repeat this step e.g. after you asked a developer to change an insufficient string or you got an announcement about changed strings like commit messages starting with "<tt>I18N: </tt>" or containing a "<tt>[I18N]</tt>" flag. | |
| − | + | :;Tip: If you have problems with this section, you download instead the "current template" from [{{URL:TP}}domain/gnucash.html the translationproject.org]. But keep in mind it is based on the last release and does not contain recent changes. | |
| − | Now | + | # If your repository is no fresh checkout, you should first [[#Update your repository]]: <Syntaxhighlight lang="sh"> |
| + | git pull --rebase | ||
| + | </Syntaxhighlight> | ||
| + | # Only on the first run see [[Building]] to set up your build environment depending on your OS. | ||
| + | #;Note: As you can use <tt>make</tt> or <tt>ninja</tt>, on this page we write always <tt>make <target></tt>. If you decided to use ninja, execute <tt>ninja <target></tt> instead. | ||
| + | # Then in gnucash, a specific command ''at the '''top-level''' of the build tree'' (or source tree, if you do not use a separate build directory) will perform all necessary steps for this: <Syntaxhighlight lang="sh"> | ||
| + | cd ${BUILDDIR} # adjust ${BUILDDIR} | ||
| + | make pot | ||
| + | </Syntaxhighlight> | ||
| + | # If make complains <Syntaxhighlight lang="console" inline>make: *** No rule to make target `<path/to/missing-source-file>', needed by `gnucash.pot'. Stop. | ||
| + | </Syntaxhighlight> there are obsolete relicts from a previous build. Just run <Syntaxhighlight lang="sh"> | ||
| + | make clean # remove obsolete files | ||
| + | make pot # try it again | ||
| + | </Syntaxhighlight> | ||
| + | # Now go into the po directory: <Syntaxhighlight lang="sh"> | ||
| + | cd ${SOURCEDIR}/po # adjust ${SOURCEDIR} | ||
| + | </Syntaxhighlight> | ||
| + | If your language file ''already exists'', continue with [[#Update an existing .po file]]. | ||
| − | == | + | === Build a new .po file === |
| − | Before you begin | + | If there is no .po file for your language, then you can start a new one. Start by |
| + | <SyntaxHighlight lang="sh"> | ||
| + | msginit [-lLL[_RR]] [-i<path/to/>gnucash.pot] | ||
| + | </SyntaxHighlight> | ||
| + | where <tt>LL</tt> is your language and <tt>RR</tt> your region code, if there is already a different LL.po like e.g. ''pt'' and ''pt_BR''. | ||
| + | : -i<path/to/>gnucash.pot is required, if you use a separate build dir, | ||
| + | : -l... is only required, if your target is different from your environments current language. | ||
| + | This will initialize the meta information with values from your user environment. | ||
| + | ;Notes: | ||
| + | :;msginit 0.21.1: seems not to know languages spoken in and around India very well. Replace <SyntaxHighlight lang="po">"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n" | ||
| + | </SyntaxHighlight> by <SyntaxHighlight lang="po">"Plural-Forms: nplurals=2; plural=n != 1;\n"</SyntaxHighlight> —or whatever is right— in the new created file. | ||
| + | :;msginit 0.19.3: is querying an obsolete address of the translation project for language teams, but that doesn't matter. | ||
| + | |||
| + | If that does not work you can copy the file <tt>gnucash.pot</tt> into a work file named <tt>LL.po</tt> and just edit this file. | ||
| + | |||
| + | ==== Adjust the header ==== | ||
| + | Only if it was not created by [[#Build_a_new_.po_file|msginit]] and updated via weblate the top of the .po file should be edited slightly. | ||
| + | |||
| + | ;Header Comments: The comments at the top of the file should be changed to be current: <SyntaxHighlight lang="po"> | ||
| + | # Indonesian translations for GnuCash package. | ||
| + | # Terjemahan bahasa Indonesia untuk paket GnuCash. | ||
| + | # Copyright (C) 2020 by the GnuCash developers and the translators listed below.# This file is distributed under the same license as the GnuCash package. | ||
| + | # Triyan W. Nugroho <triyan.wn@gmail.com>, 2020. | ||
| + | # […] | ||
| + | </SyntaxHighlight> | ||
| + | :;Copyright: Only files which were once maintained by the [[#translationproject.org]] should have a FSF copyright for that time range. | ||
| + | ::Perhaps we should use and update a copyright year range? | ||
| + | :;Translator List:Weblate will expand the copyright comment by a list of | ||
| + | ::<code><Translator name> <email address>, year[ range]</code> | ||
| + | ::in historical order. You can later copy the list into [[#Adjust_special_messages|translator-credits]] ideally in reverse order. | ||
| + | :;Conventions of your team (optional): This is also a good place to record ''typographic conventions'', if more than one person work on the file: <SyntaxHighlight lang="po"> | ||
| + | # | ||
| + | # Konventionen/Tastenkürzel: | ||
| + | # »Zitate«: [AltGr]+{[Y]|[X]} | ||
| + | # Gedankenstrich — [AltGr]+[Shift]+[-] | ||
| + | </SyntaxHighlight> | ||
| + | |||
| + | ;Header Record: The first, empty msgid "" contains information for you and the gettext tools. Each line of the msgstr contains a '''capitalized entry''', a colon and a value. ''Replace all variables (uppercase words)'' with something appropriate. In this case, you will be the first author of the translation, and also the | ||
| + | :;Last-Translator: ''your name'' and ''email address'', usually set by weblate. This person responsible for the recent change set, so we need an email address to contact you if there are issues. | ||
| + | :;Language-Team: Most languages are maintained by teams and everybody wants to get informed. That is usually the weblate language team. Before [[#translationproject.org]] or the german Gnucash translator team have been in use. | ||
| + | :: If you are not using weblate enter the teams name and email address. If you are no member of a team, keep it empty or write <code>NONE</code>. | ||
| + | ::;Tip: You can reuse this line in [[#Adjust_special_messages|translator-credits]]. | ||
| + | :;Language: Already set by <code>msginit</code> it should be the same as the filename without extension, usually the ISO code of your language. | ||
| + | :;Project-Id-Version: <Package name> (set by <code>msgint</code>) and <Version> (updated on msgmerges). | ||
| + | :;Report-Msgid-Bugs-To: Should already been set by <code>msginit</code> to <code>{{BugURL}}/buglist.cgi?roduct=GnuCash&component=Translations</code> or similar, where you can report issues with the <code>msgid</code>s like | ||
| + | ::* "There is a typo in <msgid>" or | ||
| + | ::* "<msgid> is impossible to translate to <your language> because of the grammatical difference …" | ||
| + | ::if nobody reacts on your comments in weblate. | ||
| + | :;POT-Creation-Date: gets updated by <code>msgmerge</code>. | ||
| + | :;PO-Revision-Date: The timestamp of the last modification. | ||
| + | ::* Weblate and editors with a specific po mode should update it automatically. | ||
| + | ::* If you use a normal text editor, you will have to do it manually. | ||
| + | :;Content Section: Do not change <syntaxhighlight lang="po"> | ||
| + | "MIME-Version: 1.0\n" | ||
| + | "Content-Type: text/plain; charset=UTF-8\n" | ||
| + | "Content-Transfer-Encoding: 8bit\n" | ||
| + | </syntaxhighlight> but replace its older forms like <syntaxhighlight lang="po"> | ||
| + | "CHARSET: UTF-8\n" | ||
| + | "ENCODING: 8bit\n" | ||
| + | </syntaxhighlight> with the recent form. | ||
| + | :;Plural-Forms: <code>msginit</code> should have set it properly. E.g. many slavian languages have complexer rules than English's <SyntaxHighlight lang="po"> | ||
| + | "Plural-Forms: nplurals=2; plural=n != 1;\n" | ||
| + | </SyntaxHighlight> | ||
| + | ::See [{{URL:gettext-manual}}#Translating-plural-forms Gettext Manual: Translating Plural Forms] for details. | ||
| + | :See the full explanation in [{{URL:gettext-manual}}#Header-Entry Gettext Manual: Header Entry]. | ||
| + | :* Remove the `#, fuzzy' line once you have specified the items in capitals, because once this is done the header entry is no longer fuzzy. | ||
| + | |||
| + | ==== Adjust special messages ==== | ||
| + | * There is currently one '''special string''': <SyntaxHighlight lang="po"> | ||
| + | #: gnucash/gnome-utils/gnc-main-window.c:4737 | ||
| + | msgid "translator-credits" | ||
| + | msgstr "" | ||
| + | "Christian Stimming, 2001-2021\n" | ||
| + | : | ||
| + | "Jan-Uwe Finck, 1999\n" | ||
| + | "\n" | ||
| + | "Anregungen, Kritik und Fragen zur Übersetzung an die\n" | ||
| + | "deutschsprachige GnuCash-Gemeinschaft <gnucash-de@gnucash.org>\n" | ||
| + | "Um die Moderation zu vermeiden, empfiehlt sich die Anmeldung auf der\n" | ||
| + | "<a\ | ||
| + | href=\"https://lists.gnucash.org/mailman/listinfo/gnucash-de\">Liste " | ||
| + | "gnucash-de</a>" | ||
| + | |||
| + | </SyntaxHighlight> | ||
| + | :This will appear in <tt>Help->About->Credits->Translation</tt>. So you should enter your ''name'' or that of your team and an ''email'' address where users can contact you for typos and gifts. | ||
| + | :;Tip: After some time more persons would have worked on the translation. Then you can expand it from your header comments to: <SyntaxHighlight lang="po"> | ||
| + | msgstr "" | ||
| + | "<current translator>, <years>\n" | ||
| + | "<previous translator>, <years>\n" | ||
| + | : | ||
| + | "<first translator>, <years>\n" | ||
| + | "\n" | ||
| + | "Send suggestions, critizism and questions about this translation to\n" | ||
| + | "Klingon speaking GnuCash community <gnucash-tlh@gnucash.org>\n." | ||
| + | "To avoid moderation we recommend to subscribe at\n" | ||
| + | "<a | ||
| + | # This comment exists only to trick the spamfilter. Rejoin the surrounding lines again. | ||
| + | href=\"https://lists.gnucash.org/mailman/listinfo/gnucash-tlh\">List gnucash-tlh</a>" | ||
| + | # Don't forget to replace Klingon (tlh) by your language and translate the rest! | ||
| + | </SyntaxHighlight> If a list exists, we suggest to remove the email address of individuals for data protection reasons. | ||
| + | |||
| + | ==== Prepopulate your file with translations from your glossary and other projects ==== | ||
| + | The basic idea is decribed in [{{URL:gettext-manual}}#Compendium Gettext Manual: Using Translation Compendia]. Your translator tools might already support compendia. If not, i.e you are using a plain text editor, here is the manual way: | ||
| + | |||
| + | There are in total 3 programms in use: | ||
| + | :;msgcat: Concatenates and merges the specified PO files. | ||
| + | :;msgmerge: Merges two or more Uniforum style .po files together. | ||
| + | :;msgattrib: Filters the messages of a translation catalog according to their attributes or manipulates their attributes. | ||
| + | |||
| + | :;Example: To merge a compendiumn like our glossary: <SyntaxHighlight lang="sh"> | ||
| + | cd ${SRCDIR}/po | ||
| + | # Gettext manual's suggestion to merge compendia without old po file: | ||
| + | msgmerge --compendium glossary/${LL}.po -o ${LL}.po /dev/null ${BUILDDIR}/po/gnucash.pot | ||
| + | # Perhaps better: | ||
| + | msgmerge -U ${LL}.po --compendium glossary/${LL}.po ${BUILDDIR}/po/gnucash.pot | ||
| + | </SyntaxHighlight> | ||
| + | |||
| + | ===== GOffice ===== | ||
| + | Gnucash has borrowed a couple of source files from [{{URL:GH}}GNOME/goffice goffice]. Those files contain a number of translatable strings. The goffice translation teams have already put effort in translating those in many languages. To reduce our translation effort, the script linked in [[I18N#Borrowing Code]] can be used to import these translations into our own po files. | ||
| + | |||
| + | If the goffice part for your language is incomplete, you might consider to offer them to update their file with your work. | ||
| + | |||
| + | ===== GTK3 ===== | ||
| + | Stock buttons became deprecated in their version 3.10. They included: | ||
| + | # a label with mnemonic, | ||
| + | # for which the translation was already done in the gtk domain, | ||
| + | # a unique icon was associated. | ||
| + | |||
| + | So they are no longer used since gnucash 3.0. We use still the same labels, but the GTK translation is not directly used. | ||
| + | |||
| + | You can save some work by merging the po file of your language from GTK3, i.e. from https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/po into your gnucash po file. | ||
| + | |||
| + | :;Example: To merge fitting translations from GOffice and GTK: <SyntaxHighlight lang="sh"> | ||
| + | #Example to merge common parts from po files in GOffice and GTK | ||
| + | |||
| + | # Variant A: in single steps to watch their results | ||
| + | ## 1. join 3. party translations | ||
| + | msgcat --use-first -o tmp.po ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po | ||
| + | ## 2. Remove unused messages. Authoritativ is gnucash.pot: | ||
| + | msgmerge tmp.po ${BUILDDIR}/po/gnucash.pot | msgattrib --no-obsolete > {$LL}.po | ||
| + | rm tmp.po | ||
| + | |||
| + | # Variant B: in one command: | ||
| + | msgcat --use-first ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po | \ | ||
| + | msgmerge ${BUILDDIR}/po/gnucash.pot | \ | ||
| + | msgattrib --no-obsolete > {$LL}.po | ||
| + | </SyntaxHighlight> | ||
| + | |||
| + | ==== Adjust po/CMakeLists.txt ==== | ||
| + | Also include your language code into the ''NEW_LINGUAS variable'' in the [{{URL:GH}}Gnucash/gnucash/blob/stable/po/CMakeLists.txt#L3-L4 CMakeLists.txt] file in the ''po folder'' of your ''source directory'': <SyntaxHighlight lang="sh" highlight="8"> | ||
| + | # Set of available languages: | ||
| + | set (ALL_LINGUAS ar as az bg brx ca cs da de doi el en_GB es es_NI et eu fa fi fr gu he hi hr hu id it ja kn ko kok kok@latin ks lt lv mai mni mni@bengali mr nb ne nl pl pt pt_BR ro rw sk sr sv ru ta te tr uk ur vi zh_CN zh_TW) | ||
| + | </SyntaxHighlight> | ||
| + | |||
| + | ''CMakeLists.txt'' is a file, which controls the configuration of the ''build process''. So after changing it, you have to '''rerun cmake'''. Some IDEs like [[Eclipse]] will do it automagical for you. | ||
| + | |||
| + | As part of the build your <tt>LL.gmo</tt> file is generated in the po directory of your build tree. Finally ''make install'' will copy it to the place, where it will be found at runtime. If you forget one of the steps, your translated language will not appear. | ||
| + | |||
| + | Continue with [[#Translating the .po file]]. | ||
| + | |||
| + | === Update an existing .po file === | ||
| + | |||
| + | Before you begin actual translation work, you should update the gnucash.pot | ||
file and use this to update your .po file. This process will insure that | file and use this to update your .po file. This process will insure that | ||
you have the latest translatable strings. | you have the latest translatable strings. | ||
| − | + | If your language file ''already exists'', update it using the ''msgmerge'' program. This will move the old translations of unchanged strings in the new file: <syntaxhighlight lang="sh"> | |
| − | + | msgmerge --previous -U LL.po gnucash.pot | |
| − | make | + | </syntaxhighlight> |
| + | ;Note: If you had choosen a ''separate build directory'', e.g. <tt>.build</tt>, adjust the path in above command: <syntaxhighlight lang="sh"> | ||
| + | cd ${SRCDIR}/po # adjust ${SRCDDIR} | ||
| + | export BUILDDIR=../build # adjust this | ||
| + | msgmerge --previous -U LL.po ${BUILDDIR}/po/gnucash.pot | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | ;Separate commits for "noise" and real work: You should now run <tt>git commit</tt> or ''create a patch'' <tt>"L10N:<locale>: Merge recent template"</tt>. | ||
| + | : This will contain only the "noise" from the updated pot file as usually many line numbers change. | ||
| + | :; Diff example after msgmerge: <syntaxhighlight lang="diff"> | ||
| + | #. Business options | ||
| + | -#: ../src/app-utils/app-utils.scm:303 | ||
| + | -#: ../src/business/business-gnome/gncmod-business-gnome.c:117 | ||
| + | +#: ../src/app-utils/app-utils.scm:322 | ||
| + | +#: ../src/business/business-gnome/gncmod-business-gnome.c:119 | ||
| + | msgid "Business" | ||
| + | msgstr "Geschäft" | ||
| + | </syntaxhighlight> | ||
| + | :Hiding your real changes in hundreds of such sections will make it really hard for your coworkers to find them. | ||
| + | |||
| + | After having done your [[#Translate the strings|translation]] you [[#Submitting|submit]] a second commit or patch containing your actual work <tt>"Update <locale>.po"</tt>. | ||
| + | |||
| + | You should also do it, if your current translation tool uses '''other format settings''' like line breaks as the previous tool. In this case just open the file, save it and <tt>git commit</tt> or ''create a patch'' <tt>"L10N:<locale>: Preparation: Reformating"</tt>. | ||
| + | :;Example in KBabel format: <syntaxhighlight lang="po"> | ||
| + | #: ../src/app-utils/business-prefs.scm:33 | ||
| + | msgid "The format string to use for generating customer numbers. This is a printf-style format string." | ||
| + | msgstr "Используемая строка форматирования для создания номеров клиентов. Её формат соответствует printf." | ||
| + | </syntaxhighlight> | ||
| + | :;Example in PoEDit format: <syntaxhighlight lang="po"> | ||
| + | #: ../src/app-utils/business-prefs.scm:33 | ||
| + | msgid "" | ||
| + | "The format string to use for generating customer numbers. This is a printf-" | ||
| + | "style format string." | ||
| + | msgstr "" | ||
| + | "Используемая строка форматирования для создания номеров клиентов. Её формат " | ||
| + | "соответствует printf." | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | ;Review the file header: | ||
| + | * <tt>Project-Id-Version should be ''GnuCash {{Version}}'' and | ||
| + | : <tt>POT-Creation-Date</tt> should be recent. If they are not, you probably forgot [[#Get a fresh template]] or [[#Updating an existing .po file]]. | ||
| + | * The <tt>PO-Revision-Date</tt> should be >= <tt>POT-Creation-Date</tt>. | ||
| + | Some, but not all tools will do this reliably for you. | ||
| + | |||
| + | === Translating the .po file === | ||
| + | |||
| + | Finally. You are ready to do some translating! | ||
| + | |||
| + | The .po source files are plain text files. | ||
| − | + | ==== Tools ==== | |
| − | + | Some ''plain text editors'' offer a specific ''syntax highlighting for .po file''s, but there are also specific tools you can use: | |
| + | * [{{URL:wp}}Emacs Emacs] has a po-mode to edit po files. | ||
| + | * [{{URL:wp}}Geany Geany], an editor with sytax highlighting and a little bit more | ||
| + | * [{{URL:wp}}Gtranslator GTranslator] is another tool but we recommend not to use it because the version of 2006 doesn't support all of the interesting elements inside the po file. Update this, if you know it is fixed. | ||
| + | * ''Lokalize'' is the successor of KBabel since KDE4. | ||
| + | * ''[https://poedit.net/ Poedit]'' to finish the PO file edit and build. | ||
| + | : [{{ListURL}}/pipermail/gnucash-devel/2018-September/042808.html Version 2.1.1 had issues] | ||
| + | * ''[https://poeditor.com/ POEditor]'' can be used online. | ||
| + | * ''[http://pology.nedohodnik.net/ Pology] is a Python library and collection of command-line tools for in-depth processing of PO files. Recommended in the Gettext Manual, but last released 2014-07-24. | ||
| + | * ''[{{URL:wp}}Translate_Toolkit translate-toolkit]'' is a python based suite. It is also used by sevices like weblate. | ||
| + | * Wikipedia: | ||
| + | ** [{{URL:wp}}List_of_translation_software List of translation software] | ||
| + | ** [{{URL:wp}}Comparison_of_computer-assisted_translation_tools Comparison of computer-assisted translation tools] | ||
| + | (feel free to add more tools here) | ||
| − | + | ==== Gettext source (.po) file format ==== | |
| + | ===== Record Format ===== | ||
| + | A record in a po file has the following form: <syntaxhighlight lang="po"><empty or only white-space> | ||
| + | # translator-comments | ||
| + | #. extracted-comments | ||
| + | #: reference… | ||
| + | #, flag… | ||
| + | #| msgctxt previous-message-context | ||
| + | #| msgid previous-untranslated-string | ||
| + | msgctxt optional-message-context | ||
| + | msgid untranslated-string | ||
| + | msgstr translated-string | ||
| + | </syntaxhighlight> | ||
| + | *The ''empty or only white-space'' line is the record separator. | ||
| + | *In ''translator-comments'' you can put your own notes. | ||
| + | *The ''extracted-comments'' are notes from the programmers for you. | ||
| + | * One or more ''reference''s tell you, where the message appears in the sources. | ||
| + | * The most important ''flags'' will be explained below in [[# Common Flags]] and [[#Special characters and other tips|source language format flag]] will be explained below. | ||
| + | * The ''previous-*'' entries will only appear, after <tt>msgmerge --previous …</tt> for fuzzy messages to show what changed. | ||
| + | * An ''optional-message-context'' has the purpose to distinguish equal msgids with different meanings. | ||
| + | * The ''msg*'' should explain themself above. | ||
| − | + | ;Example:Here is an example of translating some text into German: | |
| + | :;Before: <syntaxhighlight lang="po"> | ||
| + | #: messages-i18n.c:11 | ||
| + | msgid "" | ||
| + | "The GnuCash personal finance manager.\n" | ||
| + | "The GNU way to manage your money!" | ||
| + | msgstr "" | ||
| + | </syntaxhighlight> | ||
| + | :;After, the translation in the de.po file: <syntaxhighlight lang="po"> | ||
| + | #: messages-i18n.c:11 | ||
| + | msgid "" | ||
| + | "The GnuCash personal finance manager.\n" | ||
| + | "The GNU way to manage your money!" | ||
| + | msgstr "" | ||
| + | "GnuCash: Ihr persoenlicher Finanzmanager.\n" | ||
| + | "Der GNU-Weg, ihr Geld zu verwalten!" | ||
| + | </syntaxhighlight> | ||
| + | You should read through every translation in the .po file at least once. | ||
| − | + | ===== Common Flags ===== | |
| + | ====== [{{URL:gettext-manual}}#Fuzzy-Entries Fuzzy Flag] ====== | ||
| + | If you see a string that has the phrase <tt>#, fuzzy</tt> in the flags comment above it, review the translation and confirm it by removing | ||
| + | * the <tt>, fuzzy</tt> flag, but no other flags like <tt>, c-format</tt>, | ||
| + | * the <tt>#| msgid</tt> lines, and in some cases | ||
| + | * the <tt>#| msgctxt</tt> line. | ||
| + | A fuzzy translation means that the translation will be ignored by the program. | ||
| − | + | There are at least 2 reasons for the fuzzy flag: | |
| − | + | # one of the <tt>msg*</tt> programs took some guess about what the translation might be from similar msgids, | |
| + | # in a previous version you had a valid translation, but a programmer changed (parts of) the msgid. | ||
| − | + | After you finish translating, you should not have any "<tt>#, fuzzy</tt>" strings left. Remember, a string marked as "fuzzy" means it will not be translated in the program. You can filter for fuzzy messages by running <syntaxhighlight lang="sh"> | |
| − | + | cd ${SOURCEDIR}/po | |
| − | + | msgattrib --fuzzy ${YOUR_LANGUAGE}.po | |
| + | </syntaxhighlight> | ||
| − | + | ;Example fuzzy message: <syntaxhighlight lang="po" highlight="2-3,5"> | |
| − | + | #: messages-i18n.c:35 | |
| + | #, fuzzy, c-format | ||
| + | #| msgid "There was an error opening the file %s." | ||
| + | msgid "There was an error writing the file %s." | ||
| + | msgstr "Es gab einen Fehler beim Oeffnen der Datei %s." | ||
| + | </syntaxhighlight> Here the msgid was changed from "opening" to "writing". You need to correct the translated string, remove the line(s) with the old msgid "<tt>#| msgid …</tt>" and the 'fuzzy' flag, because only then the translation will actually appear in the program. | ||
| + | ;Example fuzzy fixed: <syntaxhighlight lang="po" highlight="2,4"> | ||
| + | #: messages-i18n.c:35 | ||
| + | #, c-format | ||
| + | msgid "There was an error writing the file %s." | ||
| + | msgstr "Es gab einen Fehler beim Schreiben der Datei %s." | ||
| + | </syntaxhighlight> Notice that <tt>#, c-format</tt> was ''not removed''. That is correct, you should leave that. | ||
| + | :;Tip: If all fuzzy strings were fixed (<syntaxhighlight lang="sh" inline>msgattrib --fuzzy $LL.po</syntaxhighlight> returns nothing), you can also bulk remove the previous messages with <syntaxhighlight lang="sh">msgattrib --clear-previous -o $LL.po $LL.po</syntaxhighlight> | ||
| − | + | ====== Format Flags ====== | |
| + | Because parts of GnuCash were written in different programming languages, there appear at least 2 different format flags: | ||
| + | ;c-format: Format specifier: <code>%</code> | ||
| + | :When you see the comment "c-format", it means that the format codes in the translatable string are referring to C formatting codes. So, '%s' means text, '%d' means an integer, etc... | ||
| + | ;scheme-format: Format specifier: <code>~</code> | ||
| + | ;Todo: Which parts of [[#Special_characters_and_other_tips]] would better stay here? | ||
| − | == | + | ===== Orphaned Records ===== |
| + | At the end of your file you might see records like <Syntaxhighlight lang="po"> | ||
| + | #~ msgid "Enter an Online Direct Debit Note" | ||
| + | #~ msgstr "Online-Lastschrift eingeben" | ||
| − | + | #~ msgid "Debited Account Number" | |
| + | #~ msgstr "Konto-Nr. des Zahlungspflichtigen" | ||
| + | |||
| + | </syntaxhighlight> | ||
| + | They have no reference line. This records are no longer in use and you can remove them. | ||
| + | |||
| + | ==== Translate the strings ==== | ||
| + | Each message to translate is then given in turn in the PO file. For example, an untranslated entry might be: <syntaxhighlight lang="po"> | ||
| + | #: lib/error.c:88 | ||
| + | msgid "Unknown system error" | ||
| + | msgstr "" | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | The empty '''msgstr''' string has to be filled with the translation for the string shown after '''msgid'''. If you were a German speaker, say, the entry once translated might look like: <syntaxhighlight lang="po"> | ||
| + | #: lib/error.c:88 | ||
| + | msgid "Unknown system error" | ||
| + | msgstr "Unbekannter Systemfehler" | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | You just produce a translation for all entries in the PO file, one after another, respecting the overall file format and the quoting needed for special characters, when needed. Observation and intuition may allow you to grasp what the format should be; the precise rules for PO files are given in the [{{URL:gettext-manual}} GNU gettext manual]. The msgfmt program is helpful for pinpointing formatting errors. | ||
| − | + | ===== Contexts ===== | |
| + | ;Important: With Gnucash 3.7 the first 2 forms got replaced by [[#Message Context]]. The description of the old types is only kept for some time to help updating older catalogs. | ||
| − | + | At some places, GnuCash uses "disambiguation prefixes" in translatable strings. Here is an old explanation: | |
| − | + | {{ListURL}}/pipermail/gnucash-devel/2005-October/014236.html ; more explanation is also here: https://wiki.gnome.org/GnomeI18nDeveloperTips. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | There are at least 2 ''use cases'': | |
| + | * '''Abbreviations''', i.e. for columns and their headers: <SyntaxHighlight lang="po" highlight="2,5"> | ||
| + | msgid "Reconciled" | ||
| + | msgstr "Abgeglichen" | ||
| + | : | ||
| + | msgid "Reconciled:R" | ||
| + | msgstr "Reconciled:A" | ||
| + | </SyntaxHighlight> | ||
| + | * '''Sample text''' to determinate the size of the output cell. ''Instead of a translation'' the "worst case" of expected text in your language is required here. | ||
| + | :For the following example the german tranlators copied ''the longest path'' of account names from their business account templates as shown in the accounts tab of Gnucash: <SyntaxHighlight lang="po" highlight="2"> | ||
| + | msgid "sample:Expenses:Automobile:Gasoline" | ||
| + | msgstr "sample:Aufwendungen 2/4:Reparatur/Instandhaltung:4805 Reparatur u. Instandh. von Anlagen/Maschinen u. Betriebs- u. Geschäftsausst." | ||
| + | </SyntaxHighlight> | ||
| + | :;Important: ''Keep'' the part before the colon ''untranslated''. | ||
| − | + | Another form - without need to insert the prefix - was <SyntaxHighlight lang="po"> | |
| − | + | #. Translators: This string has a context prefix; the translation | |
| − | + | #. must only contain the part after the | character. | |
| − | + | #: gnucash/gnome-utils/dialog-options.c:722 | |
| − | + | #: gnucash/gnome-utils/gnc-tree-view-account.c:908 | |
| − | + | msgid "Column letter for 'Placeholder'|P" | |
| − | + | msgstr "P" | |
| + | </SyntaxHighlight> and became <SyntaxHighlight lang="po"> | ||
| + | #: gnucash/gnome-utils/dialog-options.c:719 | ||
| + | #: gnucash/gnome-utils/gnc-tree-view-account.c:906 | ||
| + | msgctxt "Column header for 'Placeholder'" | ||
| + | msgid "P" | ||
| + | msgstr "P" | ||
| + | </SyntaxHighlight> | ||
| + | ;Tip: A tool like kdiff3 can help you to recover your previous translation. | ||
| + | ====== Message Context ====== | ||
| + | In more recently written parts we use a message context: <SyntaxHighlight lang="po" highlight="2-3"> | ||
| + | #: libgnucash/app-utils/gnc-ui-util.c:903 | ||
| + | msgctxt "Reconciled flag 'not cleared'" | ||
| + | msgid "n" | ||
| + | msgstr "" | ||
| + | </SyntaxHighlight> | ||
| − | You should | + | ===== Special characters and other tips ===== |
| − | + | ''Depending on the context'' a few characters have a special meaning and need some special treatment: | |
| − | + | ;"#" (hash): In English it is often used as abbreviation for "Number". You should replace it by "No.", "Nr." or whatever is common in your language. | |
| − | + | ;"_" (underline): In ''menu and dialog entries'' the following character will become the '''accelerator''', '''mnemonic''' or '''hotkey''', which can be used together with a superkey <code>ctrl</code> or <code>alt</code> to jump to the entry. While in [[GTK2]] they have always been visible, in [[GTK3]] they appear only after holding the superkey. More specific under ''Linux'' you reach a main '''menu''' entry with <code>alt</code>+<code><key></code> and its submenus and other menu entries with <code><key></code>. In '''dialogs''' always use <code>alt</code>+<code><key></code>. | |
| + | : The terminology is not unique here: while | ||
| + | ::[[#Desired|msgfmt]] has a <tt>--check-accelerator</tt> option and | ||
| + | ::DocBook uses the <accel> tag for ''a letter used with a meta key'' and <shortcut> for ''a key combination'', but | ||
| + | ::GTK+ distinguishes the underline marked character of the label as ''mnemonic'' and the hotkeys like <code>F1</code> for <tt>Help</tt> or <code>ctrl</code>+<code>c</code> for <tt>Copy</tt> as ''accelerator''. | ||
| + | : So the key should | ||
| + | :# exist on a keybord for your language. | ||
| + | :# be easy to remember for your users, | ||
| + | :# be ''unique in its context'' and you should control it by [[#Running GnuCash]] with your file after [[#Compile & Install]]. See also <tt>Access Keys</tt> in [{{URL:Gnome-HIG}}guidelines/keyboard.html Gnome's HIG about keyboard input]. | ||
| + | :::''wrong:'' | ||
| + | ::::"do _this" # Hotkey: t | ||
| + | ::::"do _that" # Hotkey: t => not directly reachable | ||
| + | ::::"do th_is" # Hotkey: i => thin letter, underline becomes invisible | ||
| + | :::''right:'' | ||
| + | ::::"do thi_s" # Hotkey: s | ||
| + | ::::"do th_at" # Hotkey: a | ||
| + | :::That is one of the reasons why you should [[#Optional Compile & Install|run the program with your translation]]: to see duplicate accelerators. | ||
| + | :::;Characters to avoid: | ||
| + | ::::In dialogs some are already used on buttons like in English: <code>C</code>lose, <code>H</code>elp. Others depend on the context. | ||
| + | ::::Thin letters like lowercase '''i''' or '''l''', because the underline is to short. | ||
| + | ::::Characters breaking the baseline like in latin script: '''j''','''p''','''q''','''y'''. At least in some fonts the underline becomes invisible - leaving the user clueless. | ||
| + | ::It is not required to use the same key as in English, Example from de.po: <syntaxhighlight lang="po"> | ||
| + | #: gnucash/gnome-utils/gnc-main-window.c:273 | ||
| + | msgid "_File" | ||
| + | msgstr "_Datei" | ||
| + | </syntaxhighlight> Languages are just different. | ||
| + | :;In Weblate: Compare <tt>https://hosted.weblate.org/browse/gnucash/gnucash/$LANGUAGE/?offset=1&q=_&sort_by=source&checksum=</tt>, but replace <q>$LANGUAGE</q> by your language code. | ||
| − | + | ;"\" (backslash): It is the escape character in many programming languags. The following character has a special meaning like e.g.: | |
| + | :;"\n" (New line): The most often used special character in our strings. If msgid contains "\n" keep the layout and add them to msgstr too - at the same places. | ||
| + | :;"some \"quoted\" text": Because " terminates the messages, you must precede it by a backslash inside of the messages or use other quoting characters like: | ||
| + | ::*"some 'quoted' text" | ||
| + | ::*"some »quoted« text" | ||
| + | ::*"some „quoted” text" | ||
| + | ::You are free to use the conventions which are common or suggested in your language, but stay consistent. For that purpose you should add a translator comment about the convention at the beginning of the file for better cooperation. | ||
| + | :Use <tt>"\\"</tt> to print a backslash. | ||
| + | ;"%" (percent): In C based programming languages "%" marks the beginning of a '''format specifier''', e.g. "%d6" means insert the next variable here ''in decimal format with 6 digits''. Such format specifiers should be copied into your translated message, at the appropriate spot for your language, see {{URL:Boost}}doc/libs/release/doc/html/date_time/date_time_io.html#date_time.format_flags Boost's list of format flags for date and time]. | ||
| + | :;Non-ASCII digits: As a special feature for Farsi (Persian) and maybe Arabic, translators can insert an ‘I’ flag into numeric format directives. For example, the translation of "%d" can be "%Id". The effect of this flag, on systems with GNU libc, is that in the output, the ASCII digits are replaced with the ‘outdigits’ defined in the LC_CTYPE locale category. On other systems, the gettext function removes this flag, so that it has no effect. | ||
| + | :;Note: If a string is marked with c-format and has a % mark that does '''not''' start a format specifier, [{{BugURL}}/enter_bug.cgi?product=GnuCash&component=Translations file a bugreport] and tell the developers the location of the string (the lines above the msgid). The developers should fix this in the code. One way to do so is to insert a comment containing '''<tt>xgettext:no-c-format</tt>''' before the gettext call. | ||
| + | ::In order to continue without having to wait for the developers' fix to propagate you can remove the <tt>c-format</tt> flag from the <tt>#,</tt> comment line above. If no other flags are in the line, simply remove the line. | ||
| + | :* To output "%" if a string contains format specifiers, use "%%" in your string. | ||
| + | :;Reordering parameters: Assume a string <tt>"In %d cases the result will be %d."</tt>, but in your language you would prefer to write <tt>"%d will be the result in %d cases."</tt> Now you would get the wrong numbers. | ||
| + | ::;Solution: Insert the ordinal number of the parameter, followed by "$" in the format specifier: <tt>"%2$d will be the result in %1$d cases."</tt>. | ||
| + | ;"~" (tilde): like "%", but for <tt>scheme-format</tt>. The basic scheme-format uses ~a or ~s to format subsequent variables within code and should be copied in the translated message, in the same order. Guile's <tt>(ice-9 format)</tt><ref>{{URL:guile-manual}}Formatted-Output.html</ref> does reordering with the ~@* and ~#* arguments, but it's a bit tricky to use: <syntaxhighlight lang="scheme"> | ||
| + | (format #t "~@*1~a's ~@* from ~@*2~a to ~a" "Balance Sheet" "Yoyodyne Pty" "1 Oct 2018" "30 Sept 2019") | ||
| + | </syntaxhighlight> would print <syntaxhighlight lang="console"> | ||
| + | Yoyodyne Pty's Balance Sheet from 1 Oct 2018 to 30 Sept 2019 | ||
| + | </syntaxhighlight> | ||
| + | :;Note: ~a will insert a contents using "human readable" <tt>(display var)</tt> whereas ~s will insert contents using <tt>(write var)</tt>. This is an important difference which means ~a and ~s cannot be interchanged.<ref>{{URL:guile-manual}}Scheme-Write.html</ref> | ||
| + | ;"{''num'',''optional other specifiers''}": this is a format specifier for C++ code. You cat either copy it verbatim somewhere in your translated message or you may [{{URL:Boost}}doc/libs/release/doc/html/date_time/date_time_io.html#date_time.format_flagsdoc/libs/release/libs/locale/doc/html/localized_text_formatting.html adapt it to your language]. | ||
| + | ;"$" (Dollar): Since 2023 there is another format specifier: <tt>${parameter-name}</tt>. | ||
| + | :;Example: <syntaxhighlight lang="scheme"> | ||
| + | (gnc:format "${start} to ${end}" 'start "1 Oct 2018" 'end "30 Sept 2019") | ||
| + | </syntaxhighlight> will print <syntaxhighlight lang="console"> | ||
| + | 1 Oct 2018 to 30 Sept 2019 | ||
| + | </syntaxhighlight> <ref>[{{URL:Bugs}}show_bug.cgi?id=797725 Bug 797725 - Untranslatable string "For Period Covering ~a to ~a"]</ref> | ||
| + | ;"&" (ampersand): is the starting character of [{{URL:wp}}Character_encodings_in_HTML HTML encoding], which is used in some reports. E.g. <syntaxhighlight lang="html"> </syntaxhighlight> means NonBreakableSpace. | ||
| + | ;"<" (less): is the starting charcter of tags in several markup languages. E.g. <syntaxhighlight lang="html"><b>Text</b></syntaxhighlight> results in bold '''Text'''. | ||
| + | ;See also: [[GUI Guidelines]] is the related programmers view. | ||
| − | + | ===== Almost Done ===== | |
| + | If you are almost done it becomes harder to find the last untranslated messages. Then you can use <syntaxhighlight lang="sh"> | ||
| + | msgattrib --untranslated ${LL}.po | ||
| + | </syntaxhighlight> and then search your file for the content of the msgid. | ||
| − | + | ==== Check syntax and statistics of your .po file ==== | |
| − | + | ;Required: <syntaxhighlight lang="sh"> | |
| − | + | msgfmt -c --statistics ${LL}.po | |
| − | + | </syntaxhighlight> | |
| − | + | If that program reports one or more ''fatal errors'' for your language, you should review the criticized lines of your file. | |
| − | + | :;Tip: A successful call will create a file <tt>messages.mo</tt>. If you are not using a build environment, you can move that file to | |
| − | + | ::;Linux: <tt>[[Building On Linux#Locations to which GnuCash may be installed|${PREFIX}]]/share/locale/${LL}/LC_MESSAGES/gnucash.mo</tt> | |
| − | + | :: and restart gnucash to test the program with your translation. | |
| − | + | ;Desired: In a second run you might wish to see, where you forgot to add an [[#Special characters and other tips|accelerator]]: <syntaxhighlight lang="sh"> | |
| − | + | msgfmt -c --check-accelerators="_" --statistics ${LL}.po | |
| + | </syntaxhighlight> | ||
| + | The users will love you if you fix them, too. | ||
| − | + | ==== Current status ==== | |
| − | + | To see some over all statistics how many strings are translated, you can run | |
| + | for i in *.po; do echo -n "$i:"; msgfmt -c --statistics $i;done | ||
| + | in your po directory. | ||
| − | + | ==== Priority ==== | |
| − | + | As you might have noticed, the po file for GnuCash is rather big by containing more than 4000 strings. It is somewhat helpful to look into different priorities for the different strings there. However, unfortunately the po file format doesn't enable any easy way for the GnuCash project to make the import strings differently from the less important ones. However, for a few files the developer team can give you some guidelines for the general priorities. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | The ''source code location'' aka [[#Record Format|ref[erence]]] of a string gives you some hint about its priority. In particular, the following file suffixes or file locations imply a certain priority: | |
| − | + | * '''High Priority:''' Strings from all '''*.glade''' files will be presented by the GnuCash user interface (UI) somewhere for the user. This may imply a somewhat higher priority to those strings - however, some UI elements are rarely used, so the actual location of the .glade file has an influence as well, but there isn't an easy rule for that anymore. | |
| + | :;Tip: If you wish to see the string from a *.glade file in it's context, but don't know, where it is hidden in gnucash, if | ||
| + | ::* the gnucash source files and | ||
| + | ::* the Gnome's interface builder [https://glade.gnome.org/ Glade] | ||
| + | ::are installed on your system, you can preview them for instance with <syntaxhighlight lang="sh"> | ||
| + | LANG=C glade-previewer -f ${SOURCEDIR}/gnucash/gtkbuilder/${FILENAME} | ||
| + | </syntaxhighlight><ref>Without <tt>LANG=C</tt> you would see localized standard buttons, but for now you want to see everything in US English.</ref> | ||
| + | * '''Low Priority:''' Strings from all '''*.schemas.h''' files will '''not''' appear in the gnucash UI. Instead, they are shown only inside the | ||
| + | :* Linux: ''dconf-editor'', | ||
| + | :* {{Mac}}: ''defaults'' or | ||
| + | :* Windows: ''regedit'' program when the user wants to set particular [[Glossary#G|GSettings]] keys of GnuCash. You can safely consider the .schemas.h strings with lower priority than the others. | ||
| + | ** '''Register2 feature''' is a stalled developement. The strings are only visible, if you [[#configure]]<tt> --enable-register2</tt>. Some, but not all strings are marked with a "Register2 feature" comment. | ||
| − | + | Unfortunately, there is no such simple rule for strings from *.c files or the single large intl-scm/guile-string.c file. The strings from there may be of higher or lower priority, but this isn't easily visible. We can only recommend to start GnuCash on your own with your updated translation, and then check for strings which you see but are not yet translated. Those are for sure of high priority. | |
| − | |||
| − | |||
| − | + | Two additional source code locations can be noted as low priority: | |
| + | * Everything from the file ''src/bin/gnucash-bin.c'' is of '''low priority''' because those are the command line options when running gnucash with different options from the command line. This is a use case that is performed only by highly experienced users which are accustomed to using the English-language command line commands. Therefore, translations here are of lower priority. | ||
| + | * Everything from the folder ''src/tax'' or from the intl-scm/guile-string.c file with a comment indicating some file in ''src/reports/locale-specific'' is related to tax preparation in the U.S. or in Germany. Hence, those strings are uninteresting for anyone living in different countries, and you can safely consider those with very '''low priority'''. | ||
| + | === Testing and submitting your translations === | ||
You must check that your new translations are programatically correct (ie: | You must check that your new translations are programatically correct (ie: | ||
| − | that there are no unclosed quotes, etc). | + | that there are no unclosed quotes, etc). To do this, use the msgfmt program <syntaxhighlight lang="sh"> |
| + | msgfmt -c --statistics $LL.po | ||
| + | </syntaxhighlight> | ||
| + | Above call will report most important errors in your .po file and ''must not fail'', while the call below | ||
| + | msgfmt -c --check-accelerators="_" --statistics LL.po | ||
| + | whill additionally check if you missed some keyboard accellerators aka hotkeys. | ||
| + | |||
| + | ;Note for developers: Another python based tool is '''i18nspector''' - checking tool for gettext POT, PO and MO files. It is stricter and shows also warnings about expected entries which our .pot file is currently missing. That can be discussed e.g. in [[#Background]]. | ||
| + | |||
| + | If you want to see your translations within a running version of gnucash, | ||
| + | simply place your .po file in the po/ directory of your local gnucash source repository (which | ||
| + | you have previously installed) and a regenerate your message catalogs with: | ||
| + | <Syntaxhighlight lang="sh"> | ||
| + | cd ${BUILDIDR} # adjust to navigate to your build directory | ||
| + | make po-gmo | ||
| + | </Syntaxhighlight> | ||
| + | |||
| + | Now you can run gnucash with your new translations: | ||
| − | + | <Syntaxhighlight lang="sh"> | |
| + | cd ${BUILDIDR} # adjust to navigate to your build directory | ||
| + | LANG=XXXX ./bin/gnucash | ||
| + | </Syntaxhighlight> | ||
| − | + | To review the schema strings you can use 'dconf-editor' | |
| − | If you | + | ==== Alternative Way with Poedit ==== |
| − | + | If you use Poedit while working on .po file, you would notice that it saves file in .mo format, the very format that GnuCash uses itself. So one would just need to copy this LL.mo file into appropriate subdirectory of your build directory: | |
| − | |||
| − | |||
| − | + | <Syntaxhighlight lang="sh"> | |
| + | cp ${LL}.mo ${BUILDDIR}/share/locale/${LL}/LC_MESSAGES/gnucash.mo # replace ${BUILDDIR} with the actual path to your build directory | ||
| + | </Syntaxhighlight> | ||
| − | + | The only thing that needs to be changed here is <LL> which stands for your language code (ka Georgian, de German etc). The rest is as in above method: | |
| − | LANG=XXXX / | + | <Syntaxhighlight lang="sh"> |
| + | cd ${BUILDDIR} # adjust to navigate to your build directory | ||
| + | LANG=$XXXX ./bin/gnucash | ||
| + | </Syntaxhighlight> | ||
| − | + | === Submitting === | |
| − | + | just push your commit ([[Git#Pull Requests]]) or upload the [[Git#Patches]] of the files. | |
| + | There should be one commit/patch containing the noise as described in [[#Update an existing .po file]] and a second one containing your actual work. | ||
| − | + | Then follow [[#How to submit changes directly to GnuCash]]. | |
| − | + | See also {{ListURL}}/pipermail/gnucash-devel/2009-January/024700.html [FIXME: obsolete?] | |
| − | == | + | ==== Committers ==== |
| + | * Did you get [[#The glossary file]], too? | ||
| + | * Ideally [[#Updating an existing .po file]] | ||
| + | * Checks: | ||
| + | **[[#Check_syntax_and_statistics_of_your_.po_file]]! | ||
| + | *:Notify the statistics for the commit message. | ||
| + | ** The Python tool <tt>i18nspector</tt> finds many additional errors, particular bad header lines. But its language list is incomplete as it knows not many 3-letter-languages. | ||
| + | **Some common mistakes: | ||
| + | ::;msgid "translator-credits": should contain at least the "Last-Translator:" from the header. | ||
| + | ::;msgid "gnucash-icon": do not translate, we have only one. | ||
| − | + | * If the language is ''new'' | |
| + | ** [[#Adjust po/CMakeLists.txt]] already done? | ||
| + | * On committing add the name and email address of the last translator from the file as author, e.g. <syntaxhighlight lang="sh"> | ||
| + | git commit --author="Lieutenant Worf <lt.worf@starfleet.org>" --message="L10N:tlh[: optional status or other details] | ||
| − | + | 4677 translated messages." # << The msgfmt statistics | |
| − | + | </syntaxhighlight> | |
| − | + | * If you check in a new language, remove a language or see the status of the language changes from partial to (almost) complete, update the numbers in ''<sect2 id="oview-featuresintl2">'' in file '''guide/C/ch_oview.xml''' of ''gnucash-docs''. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | === Problems=== | |
| − | + | ==== Gtk-CRITICAL messages ==== | |
| + | '''Note:''' Fixing this problem is quite difficult. We keep the explanation here in case some developers need it in the future, but if you have no idea what we are talking about in the next sentences, you should rather ignore these Gtk-CRITICAL messages and our explanation here! | ||
| − | |||
If you see any "Gtk-CRITICAL" messages while running gnucash, it is probably | If you see any "Gtk-CRITICAL" messages while running gnucash, it is probably | ||
because you translated a string differently than how it exists in some other | because you translated a string differently than how it exists in some other | ||
| − | gnome library. You must discover which string you | + | gnome library. You must discover which string you translated differently, and |
change the translation to exactly match that of the gnome libraries. | change the translation to exactly match that of the gnome libraries. | ||
To do this, you need to run gnucash under gdb: | To do this, you need to run gnucash under gdb: | ||
| − | + | <Syntaxhighlight lang="sh"> | |
| + | cd ${BUILDIDR} # adjust to navigate to your build directory | ||
| + | LANG=§XXXX gdb ./bin/gnucash | ||
| + | </Syntaxhighlight> | ||
| − | Then, from within gdb, issue | + | Then, from within gdb, issue <Syntaxhighlight lang="sh"> |
| − | + | run --g-fatal-warnings | |
| + | </Syntaxhighlight> | ||
| − | Eventually, gnucash should crash ( | + | Eventually, gnucash should crash (because of the --g-fatal-warnings |
| − | directive), when it does, issue from within gdb | + | directive), when it does, issue from within gdb <Syntaxhighlight lang="sh"> |
| + | backtrace | ||
| + | </Syntaxhighlight> | ||
| − | + | You should see some output that looks like <Syntaxhighlight lang="console"> | |
| − | + | #0 0xffffe002 in ?? () | |
| − | You should see some output that looks like | + | #1 0x42028a73 in abort () from /lib/tls/libc.so.6 |
| − | + | #2 0x4019d3d8 in g_logv () from /usr/lib/libglib-1.2.so.0 | |
| − | + | #3 0x4019d414 in g_log () from /usr/lib/libglib-1.2.so.0 | |
| − | + | #4 0x40500fdd in gtk_type_check_object_cast () from | |
| − | + | /usr/lib/libgtk-1.2.so.0 | |
| − | + | #5 0x407292e5 in gnc_mdi_tweak_menus (mc=0x825adb0) at gnc-mdi-utils.c:574 | |
| − | + | #6 0x40729d13 in gnc_mdi_child_changed_cb (mdi=0x8266fd8, prev_child=0x0, | |
| − | + | data=0x8265fd8) at gnc-mdi-utils.c:861 | |
| − | + | </Syntaxhighlight> | |
| − | |||
| − | |||
Notice position #5 which has "gnc_mdi_tweak_menus at | Notice position #5 which has "gnc_mdi_tweak_menus at | ||
gnc-mdi-utils.c:574"? Open that source file and find line 574: | gnc-mdi-utils.c:574"? Open that source file and find line 574: | ||
| − | + | <Syntaxhighlight lang="c" line start=573> | |
| − | + | widget = gnc_mdi_child_find_menu_item(mc, "_View/_Toolbar"); | |
| − | + | gtk_signal_handler_block_by_data(GTK_OBJECT(widget), info); | |
| + | </Syntaxhighlight> | ||
So, the problem is with the translation of "_View/_Toolbar". The "/" is a | So, the problem is with the translation of "_View/_Toolbar". The "/" is a | ||
menu seperator, so you now know that the problem is with either the | menu seperator, so you now know that the problem is with either the | ||
| − | translation of "_View" or "_Toolbar". | + | translation of "_View" or "_Toolbar". By switching to an English gnucash (LANG=C) |
| − | and looking through your .po file, you should be able to find the problem. | + | and looking through your .po file, you should be able to find out the problem. |
Change the offending translation to whatever you see in the gnucash app. | Change the offending translation to whatever you see in the gnucash app. | ||
Remember that the translations must contain the proper underscores. | Remember that the translations must contain the proper underscores. | ||
| − | + | ==== Watch File accesses ==== | |
| − | To follow gnucash as it access files | + | To follow gnucash as it access files <Syntaxhighlight lang="sh"> |
| − | + | strace /opt/gnucash-git/bin/gnucash | |
| − | + | </Syntaxhighlight> | |
| − | |||
| − | |||
| − | |||
| − | + | == Check Files in Repo gnucash's doc Directory == | |
| + | ;Note: The content of this directory got some cleanup by <s>[{{BugURL}}/show_bug.cgi?id=797111 bug 797111]</s>. | ||
| − | + | In theory one could create localized man pages (<command>.<man-section>[.in]). But their content is almost the same as <tt><command> --help</tt>, which are translated for <tt>gnucash</tt> and <tt>gnucash-cli</tt>. | |
| − | + | ;Task: We should use gettext also in the perl modules. | |
| − | + | * If you add files add them to <tt>set(doc_DATA ...)</tt> in [{{URL:GH}}Gnucash/gnucash/blob/stable/doc/CMakeLists.txt CMakeLists.txt]. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | == Translating the GnuCash Manual and Guide== | |
| − | + | Moved to [[Documentation Translation]]. | |
== How to translate the files containing the new account hierarchies== | == How to translate the files containing the new account hierarchies== | ||
| Line 400: | Line 986: | ||
containing the new account hierarchies. | containing the new account hierarchies. | ||
| − | # | + | === Preliminary Considerations === |
| − | # | + | :However, please take a moment to think about the intention of the account hierarchy templates. The intention of those files is much more language-related than any other of the files inside gnucash. A string-by-string translation is not the best thing to do here. Instead, you can and should find out an actual recommended account structure which makes sense in your language, and implement that one in your language. By this, I mean several of the english accounts make sense only in the U.S., but probably not in other countries. Hence, your translated account template should not contain them. Also, you can add additional parts of the account templates for your language as well, if the users are likely to need it. |
| − | # | + | |
| + | :For example, in the U.S., users are likely to own a car, and for this reason there is an account structure template for "Car". If in another hypothetical region users are likely to own, say, a spaceship instead of a car, you should remove the "Car" template and instead create a new account structure that represents all accounts related to the ownership of a spaceship, and offer this as additional "Spaceship" template. | ||
| + | |||
| + | :In other words, you should feel free to create a completely new account template structure that is most suited to your language. The english-language templates are just a proposal, but will need further adaption and not a string-by-string translation. | ||
| + | |||
| + | Having said that, here is how you would start for a direct translation of the English templates: | ||
| + | |||
| + | In this section always replace <tt><locale></tt> with your [[#Naming Convention|language code]] and ''optional'' your region code, if there are multiple countries with the same language and your templates are fitting only to one of them. | ||
| + | |||
| + | === Prerequisite === | ||
| + | * If not done before, [[#Get the source from Git]]. | ||
| + | |||
| + | === Initialize accounts/<locale> === | ||
| + | * If it does not already exists, execute the following steps to initialize your <tt>accounts/<locale></tt> directory: | ||
| + | # Copy the directory <tt>accounts/C</tt> to <tt>accounts/<locale></tt>. | ||
| + | #;Tip: If there is already a directory in your language, but for a different region you can instead also copy that. | ||
| + | # In the directory <tt>accounts/</tt> change the file CMakeLists.txt and add your <locale> to both alphabetical sorted lists: | ||
| + | ## <syntaxhighlight lang="CMake"> | ||
| + | add_subdirectory(C) | ||
| + | : | ||
| + | add_subdirectory(<locale>) | ||
| + | :</syntaxhighlight> | ||
| + | ## <syntaxhighlight lang="CMake">set(accounts_DIST ${C_DIST} ... ${<locale>_DIST} ... ${dist_list} PARENT_SCOPE)</syntaxhighlight> | ||
| + | # In <tt>accounts/<locale>/CMakeLists.txt</tt> adjust the <locale>: <syntaxhighlight lang="CMake"> | ||
| + | : | ||
| + | set_dist_list(<locale>_DIST ${dist_account_DATA} CMakeLists.txt) | ||
| + | |||
| + | install(FILES ${dist_account_DATA} DESTINATION ${ACCOUNTS_INSTALL_DIR}/<locale>) | ||
| + | file(COPY ${dist_account_DATA} DESTINATION ${ACCOUNTS_BUILD_DIR}/<locale>) | ||
| + | </syntaxhighlight> | ||
| + | #;Note: The next 2 steps are are discussed in [[#Localize the Account Charts]] below. | ||
| + | # Localize <tt>acctchrt_full.gnucash-xea</tt>. This is only a helper file where you have all accounts in their context. | ||
| + | # Now create the real modules by merging the respective parts from <tt>acctchrt_full.gnucash-xe</tt> in the other acctchrt_*.gnucash-xea files. | ||
| + | * If you remove or create new files, adjust in <tt>accounts/<locale>/CMakeLists.txt</tt> the list <syntaxhighlight lang="CMake"> | ||
| + | set(dist_account_DATA | ||
| + | ...) | ||
| + | </syntaxhighlight> | ||
| + | * Whenever you changed one or more <tt>CMakeLists.txt</tt> files, you have to rerun <syntaxhighlight lang="sh"> | ||
| + | cd ${SOURCEDIR} | ||
| + | cmake <your options> | ||
| + | cd ${BUILDDIR} # e.g. .build | ||
| + | make # or ninja</syntaxhighlight> | ||
| + | |||
| + | === Localize the Account Charts === | ||
| + | '''Tip:''' <tt>C/acctchrt_full.gnucash-xea</tt> is a helper file. Because we prefer modularization it usually is not part of the distribution. It contains the full tree of the ''personal en_US accounts''. The other <tt>acctchrt_*.gnucash-xea</tt> files contain single branches of that. So after translating it you can copy&paste the respective parts in the other files to ensure consistency between them. | ||
| + | |||
| + | If you modularize the templates you should start with <tt>acctchrt_common.gnucash-xea</tt> - it is the most basic. | ||
| − | For each file: | + | For each ''desired'' <tt>acctchrt_*</tt> file in that directory: |
| − | # Change the gnc-act:title, gnc-act:short-description, and | + | # Change the <tt>gnc-act:title</tt>, <tt>gnc-act:short-description</tt>, and <tt>gnc-act:long-description</tt> to contain appropriately translated text. Do not add any newlines in the long description except at the end and begining of the string. |
| − | + | # For each <tt>gnc:account</tt> in the file | |
| − | + | ## translate the <tt>act:name</tt>, and <tt>act:description</tt> fields. | |
| − | + | ## Optionally you can | |
| − | # For each gnc:account in the file translate the act:name, and | + | ### assign an '''account number''' <tt><act:code>1234</act:code></tt> after <tt><act:commodity-scu></tt> or |
| − | + | ### add a '''note''' as i.e. in <syntaxhighlight lang="xml" highlight="6-9"> <act:slots> | |
| + | <slot> | ||
| + | <slot:key>hidden</slot:key> | ||
| + | <slot:value type="string">true</slot:value> | ||
| + | </slot> | ||
| + | <slot> | ||
| + | <slot:key>notes</slot:key> | ||
| + | <slot:value type="string">Some additional text about the usage of this account</slot:value> | ||
| + | </slot> | ||
| + | <slot> | ||
| + | <slot:key>placeholder</slot:key> | ||
| + | <slot:value type="string">true</slot:value> | ||
| + | </slot> | ||
| + | </act:slots> | ||
| + | </syntaxhighlight> | ||
| + | #: Please do ''not translate'' any other fields or the internally used ROOT account. | ||
| + | # To avoid typos, run the [[Account Hierarchy Template#Syntax Check]]. | ||
| + | # New files to be shown to the user must be added to the <tt>account_DATA</tt> section, | ||
| + | #:helper files like ''acctchrt_full.gnucash-xea'' to <tt>EXTRA_DIST</tt> in <tt>Makefile.am</tt>. | ||
| − | Note: You absolutely don't need to translate all of the files from | + | '''Note again:''' You absolutely don't need to translate all of the files from |
| − | accounts/C. A subset of those are fine as well. Probably several of | + | <tt>accounts/C</tt>. A subset of those are fine as well. Probably several of |
them will not apply to your local legislative/economic system anyway. | them will not apply to your local legislative/economic system anyway. | ||
For a really customized account hierarchy you might better create a | For a really customized account hierarchy you might better create a | ||
| Line 420: | Line 1,070: | ||
tags from the accounts/C/acctchrt_* files. | tags from the accounts/C/acctchrt_* files. | ||
| − | ---------------------------------------------------------------------- | + | If you wish to add '''new accounts''' manually, you will need some additional ''guids'', those funny random numbers. To get them you can use: <SyntaxHighlight lang="sh"> |
| + | uuidgen | sed -e 's/-//g' | ||
| + | </SyntaxHighlight> | ||
| + | or use an online uuid generator like [https://www.guidgenerator.com/ this one] (any other one will do as well). Be sure to untick "Hyphens" to generate gnucash compatible guids. If you forget or the site you use doesn't offer that option, simply remove the hyphens yourself. | ||
| + | ;Dependencies:''uuidgen'' is in a package ''''util-linux'''', '''sed''' has its own package. <!-- on opensuse; add different names for other distris --> | ||
| + | |||
| + | [[Account Hierarchy Template]] describes, how to create new templates e.g. for business purpose according local rules. | ||
| + | |||
| + | === Test your Work === | ||
| + | To test your work under real conditions, you should finally [[#Compile_.26_Install|Compile & Install]] it. But before you need an adjusted '''Makefile.am''' in your accounts/<locale> directory. If none exists, copy that from <tt>accounts/c</tt> and adjust it: | ||
| + | * 1. Line (accountdir): adjust the locale. | ||
| + | * If you removed accountcharts, remove their line from <tt>account_DATA</tt>, | ||
| + | * if you added new files, insert lines with their names and "\" (the line continuation symbol). | ||
| + | |||
| + | == How to create localized Income Tax Tables == | ||
| + | ;Note: This section is under developement and mostly untested! | ||
| + | |||
| + | As of the beginning of 2015 there is a nice US tax module, with a report and export in TXF format, and a small German (de_DE) derivate for the monthly VAT declaration. You can compare them to see how you can tweak them to get something else. | ||
| + | |||
| + | === Tax Table === | ||
| + | Because it is also used by <tt>Edit->Tax Report Options</tt>it is part of the [{{URL:GH}}Gnucash/gnucash/tree/stable/libgnucash/tax/ GnuCash library]: | ||
| + | # Copy <tt>us</tt> into a new subfolder with the lowercased ISO code of your region. | ||
| + | #:It contains the following files | ||
| + | ## tax.scm - is only a linking element, where you have to replace <tt>us</tt> by your region twice. | ||
| + | ## txf.scm - the tables, and | ||
| + | ## txf-help.scm - the descriptive help strings for each TXF code. This is also used to get a table in gnucash-docs/help/ | ||
| + | #They have relative simple table structures: <syntaxhighlight lang="scm"> | ||
| + | (define txf-tax-entity-types | ||
| + | </syntaxhighlight> | ||
| + | #:contains a list of forms for different entities (person, company …). <syntaxhighlight lang="scm"> | ||
| + | (define txf-income-categories … | ||
| + | (define txf-expense-categories … | ||
| + | </syntaxhighlight> | ||
| + | #: contain for each of the above lists the entries. If you compare this file with the respective files in <tt>de</tt>, you can see an example localization with additional categories: <syntaxhighlight lang="scm"> | ||
| + | (define txf-asset-categories … | ||
| + | (define txf-liab-eq-categories … | ||
| + | </syntaxhighlight> | ||
| + | #: It should be possible to adapt the lists for your tax forms. | ||
| + | |||
| + | === Report and Export=== | ||
| + | Probably you need to have other export reports. That are in | ||
| + | {{URL:GH}}Gnucash/gnucash/tree/stable/gnucash/report/reports/locale-specific/us like | ||
| + | * txf-export.scm | ||
| + | * us.scm is unused | ||
| + | Here you might probably need some help from a programmer. | ||
| + | |||
| + | == How to translate the website == | ||
| + | :;Note about OS: These instructions are written for linux. They will probably work on other unix-like systems as well, but not on Windows. On Windows you may be able to do this if you set up a linux-like environment (with cygwin or MinGW[-w64]), but that's untested so far. Please report your findings here. | ||
| + | |||
| + | * Get a checkout of {{URL:GH}}Gnucash/gnucash-htdocs | ||
| + | * Run the command <syntaxhighlight lang="sh">make pot</syntaxhighlight> | ||
| + | * Then depending on whether or not a translation for you language exists already (complete or not): | ||
| + | *;Existing translation:<br>Run the command <Syntaxhighlight lang="sh"> | ||
| + | msgmerge --previous -U po/LL.po po/gnucash-htdocs.pot | ||
| + | </syntaxhighlight> where LL is your language code, see [[#Naming Convention]] above. | ||
| + | *:;Alternative: <syntaxhighlight lang="sh">make msgmerge</syntaxhighlight> will update ''all'' .po files | ||
| + | *;New translation:<br> In the po directory run | ||
| + | *:;As translator: <syntaxhighlight lang=sh>msginit</syntaxhighlight> This will insert your name, email and locale settings into the new file. If that fails copy the newly created file po/gnucash-htdocs.pot to po/LL.po, where LL is your language code, see [[#Build a new .po file]] earlier. | ||
| + | *:;As maintainer: <syntaxhighlight lang=sh># Set LL=<language code> | ||
| + | msginit --no-translator --locale=$LL</syntaxhighlight> This will create a new file $LL.po without personal data. Continue with [[#Maintainers Task]]. | ||
| + | * Translate the po/LL.po file as described in [[#Translating the .po file]]. | ||
| + | *;Priority: | ||
| + | ::;High: Startpage: {index|externals/*}.phtml | ||
| + | ::;Low: sizing.phtml (outdated) search/templates/NMZ.* (unused) | ||
| + | ::;Medium: the rest depends on you. | ||
| + | * Run <syntaxhighlight lang="sh">msgfmt -c --statistics po/LL.po</syntaxhighlight> to see your success. | ||
| + | * Optionally run <Syntaxhighlight lang="sh">recode -d <input_encoding>..h0 po/LL.po</Syntaxhighlight> to get special characters HTML quoted. | ||
| + | * Send your LL.po either as | ||
| + | ** GitHub Pull Request or | ||
| + | ** attachment of a Bugzilla enhancement request to the mainteiner team. | ||
| + | |||
| + | == Background == | ||
| + | This section was started to get some overview, '''work in progress!''' | ||
| + | Beyond it helped to get rid of the outdated [[#IntlTool]] in version 2.7.6. | ||
| + | For details see the [{{URL:gettext-manual}} GetText Manual]. | ||
| + | |||
| + | === Packages === | ||
| + | In our build process we use beneath self written scripts the following packages: | ||
| + | * glib2-devel: glib-gettextize | ||
| + | * gettext, probably broken in: | ||
| + | ** -runtime: msgfmt, ... | ||
| + | ** -tools: (autopoint), gettextize, msg*, xgettext, ... | ||
| + | ** -runtime-tools-doc: manuals etc. | ||
| + | * (only up to 2.7.5) intltool: Intltool* | ||
| + | |||
| + | === Our Build Process === | ||
| + | This was the old (upto 2.6) autotools build process, which went through the following scripts: | ||
| + | |||
| + | ====== autogen.sh ====== | ||
| + | ;Note: Autotools were only used up to 2.6 branch. 2.7 and later use [[CMake]] instead. | ||
| + | ;glib-gettextize: helps to prepare a source package for being internationalized through gettext. It is a ''variant of the gettextize'' that ships with gettext. | ||
| + | :glib-gettextize differs from gettextize in that it doesn't create an intl/ subdirectory and doesn't modify po/ChangeLog (note that newer versions of gettextize behave like this when called with the --no-changelog option). | ||
| + | |||
| + | »Note that on GNU systems, you ''don't need to link with libintl'' because the '''gettext library functions are already contained in GNU libc'''.« (glibc) [{{URL:gettext-manual}}#Overview]. | ||
| + | |||
| + | ====== configure.ac ====== | ||
| + | * Sets | ||
| + | ALL_LINGUAS= ... | ||
| + | In recent versions it can be substituted by LINGUAS files in the po directories. We should consider this to distinguish TP vs. GC maintained translations. | ||
| + | GETTEXT_PACKAGE=gnucash | ||
| + | This is intltool style. Gettext uses PACKAGE=... | ||
| + | AC_SUBST(GETTEXT_PACKAGE) | ||
| + | AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, "$GETTEXT_PACKAGE", | ||
| + | [GetText version number]) | ||
| + | |||
| + | AM_GNU_GETTEXT_REQUIRE_VERSION|AM_GNU_GETTEXT_VERSION(x.yy.zz) can be used to require a version. We should use it to avoid ... | ||
| + | * TP expects > 0.11. | ||
| + | * gnulib expects >= 0.17 | ||
| + | * RHEL7 offers 0.18.2 (RHEL6 0.17) | ||
| + | * Debian Stable offers 0.18.1 and in backport 0.19.3 | ||
| + | * '''Glade2 msgctxt''' and Glade3 were implemented in 0.18.3 - July 2013 | ||
| + | * '''GSettings''' and '''Desktop''' entries are implemented in 0.19 - June 2014 | ||
| + | * and got bugfixes until Version 0.19.3 - October 2014 | ||
| + | * '''Scheme''' format strings got a fix in 0.19.4 - December 2014 | ||
| + | * '''AppData''' support: [https://lists.gnu.org/archive/html/info-gnu/2015-09/msg00003.html gettext-0.19.6 released] - 2015-09 | ||
| + | * ? custom XML formats in 0.19.7 | ||
| + | :<gjanssens> GtkUIManager files don't contain translatable strings as far as I know. They're not in POTFIILES.in either. | ||
| + | * at the time of our last update: [https://lists.gnu.org/archive/html/info-gnu/2016-06/msg00006.html gettext-0.19.8.1 released] - 2016-06 | ||
| + | * [{{BugURL}}/show_bug.cgi?id=725296#c21 gjanssens sv->swedish patch for Windows] is in gettext 0.20. It is also the first version , which extracts <developer_name> from appdata.xml. [{{ListURL}}/logs/2020/01/15.html#T15:20:46 IRC log] | ||
| + | * recent: [https://lists.gnu.org/archive/html/info-gnu/2019-05/msg00011.html GNU gettext 0.20.1 released] - May 12, 2019 | ||
| + | |||
| + | This setting then can be used by autoPoInt. Watch the caveaets from https://www.gnu.org/software/gnulib/manual/html_node/gettextize-and-autopoint.html: | ||
| + | : On the other hand, if your package is not as concerned with compliance to the latest standards, but instead favors development on stable environments, the steps are: | ||
| + | :# Determine the oldest version of gettext that you intend to support during development (at this time, gnulib recommends going no older than version 0.17). Run autopoint (not gettextize) to copy infrastructure into place (newer versions of gettext will install the older infrastructure that you requested). | ||
| + | :# Invoke gnulib-tool, and import the gettext-h module. # Fixme: Meaning? | ||
| + | |||
| + | :Regardless of which approach you used to get the infrastructure in place, the following steps must then be used to preserve that infrastructure (gnulib’s bootstrap script follows these rules): | ||
| + | :# When a script of yours run autopoint, invoke gnulib-tool afterwards. | ||
| + | :# When you invoke autoreconf after gnulib-tool, make sure to not invoke autopoint a second time, by setting the AUTOPOINT environment variable, like this: | ||
| + | ::<pre>$ env AUTOPOINT=true autoreconf --install</pre> | ||
| − | + | AM_GLIB_GNU_GETTEXT # FIXME: Meaning? | |
| − | + | *runs checks with settings | |
| + | ** AC_PROG_INTLTOOL | ||
| + | ** AC_CHECK_HEADERS(ltdl.h, ... | ||
| + | dnl Make sure we have a proper gettext installed | ||
| + | AC_MSG_CHECKING(for a valid gettext/gmsgfmt installation) | ||
| + | if test "$gt_cv_have_gettext" != "yes" || test "x$GMSGFMT" = "x"; then | ||
| + | AC_MSG_RESULT(no) | ||
| + | AC_MSG_ERROR([Cannot find Glib Gettext. Maybe you need to install the gettext package?]) | ||
| + | else | ||
| + | AC_MSG_RESULT(yes - $GMSGFMT) | ||
| + | fi | ||
| − | + | ====== makefile.am ====== | |
| + | has the following section: | ||
| + | .PHONY: pot | ||
| + | pot: Makefile po/POTFILES.in | ||
| + | rm -f po/$(PACKAGE).pot | ||
| + | ${MAKE} -C po $(PACKAGE).pot | ||
| + | |||
| + | |||
| + | $(srcdir)/po/POTFILES.in: make-gnucash-potfiles .potfiles | ||
| + | if test -w $(srcdir)/po/POTFILES.in ; then ./'''make-gnucash-potfiles''' > $(srcdir)/po/POTFILES.in ; fi | ||
| + | |||
| + | # Creation rules so that po/gnucash.pot can always be created for | ||
| + | # make dist. | ||
| + | po/gnucash.pot: po/POTFILES.in | ||
| + | ${MAKE} -C po gnucash.pot | ||
| + | |||
| + | .potfiles: | ||
| + | |||
| + | ====== make-gnucash-potfile.in ====== | ||
| + | This is a self written perl script from the time as gettext had several issues. It creates '''po/potfiles.in''', the "list of files which contain translatable strings". This script is not used in a cmake based build environment for gnucash. As gnucash 2.7.4 and more recent is cmake only, this file has been removed starting from that release. | ||
| + | |||
| + | ====== xgettext ====== | ||
| + | |||
| + | ;xgettext: Extract translatable strings from given input files. See --language for supported list: | ||
| + | :;--language=NAME: recognise the specified language ('''C''', '''C++''', ObjectiveC, PO, Shell, ''Python'', Lisp, EmacsLisp, librep, '''Scheme''', Smalltalk, Java, JavaProperties, C#, awk, YCP, Tcl, ''Perl'', PHP, GCC-source, NXStringTable, RST, '''Glade''', Lua, JavaScript, Vala, '''Desktop''') | ||
| + | :Options, which we should check: | ||
| + | :;--copyright-holder=STRING: set copyright holder in output | ||
| + | :;--foreign-user: omit FSF copyright in output for foreign user | ||
| + | :;--msgid-bugs-address=EMAIL@ADDRESS: set report address for msgid bugs | ||
| + | <References /> | ||
Latest revision as of 15:53, 13 May 2024
| Languages | 简体中文 | עִברִית |
|---|
- Tip
- Use Google translation and select your language to get a machine translation of this document.
The concept of this document is to give you step-by-step instructions on how to create or update translations and other localization tasks for the gnucash project.
There are related pages for
- programmers: I18N and
- project maintainers: Language_Administration.
Contents
- 1 Overview
- 2 Available Resources
- 3 How to submit changes directly to GnuCash
- 4 Translating the Program
- 4.1 Get the source from Git
- 4.2 Get packages, which are used while building
- 4.3 Steps in the Build System
- 4.4 Naming Convention
- 4.5 The glossary file
- 4.6 Get a fresh template
- 4.7 Build a new .po file
- 4.8 Update an existing .po file
- 4.9 Translating the .po file
- 4.10 Testing and submitting your translations
- 4.11 Submitting
- 4.12 Problems
- 5 Check Files in Repo gnucash's doc Directory
- 6 Translating the GnuCash Manual and Guide
- 7 How to translate the files containing the new account hierarchies
- 8 How to create localized Income Tax Tables
- 9 How to translate the website
- 10 Background
Overview
GnuCash has several separate areas that need translations or localization, which are by priority:
- The Glossary
- A reference in form of a message catalog with terms that are commonly used throughout GnuCash's other components and their explanation. Preferably it should be translated first for each new language to define a consistent terminology for the other parts.
- The Program
- Its message catalogs contain all text messages for the application's user interface. Not all are equally important though.
- Please read at least #Adjust special messages and #Special characters and other tips, if you use one of that services.
- The Windows Installer
- It contains some 20 strings.
- The Account Templates
- A set of ready to use account chart snippets for personal users that can be mixed and matched into a full chart of accounts during the creation of a new a new GnuCash file with currently 115 translatable account names.
- If your government or other authorities offer specific templates for business users, you can create them, too.
- The Documentation
- The Help Manual and the Tutorial and Concepts Guide. These documents explain how to use GnuCash. They are written in DocBook, an XML variant.
- The Website
- While mostly written in PHP/HTML, it uses message catalogs, too.
- In theory one could also translate recent announcements from the news directory into the language specific subfolder, but ususally there are more important tasks around.
- The Income Tax Tables
- They require some knowledge of your regional tax rules and are related to account templates.
- Currencies
- GnuCash uses the translation of the ISO 4217 currency codes and names. This are maintained by the ISO Codes Team. If your language is missing or has issues contact them or contribute:
- Optionally you can #Check Files in Repo gnucash's doc Directory files, too.
Available Resources
There are many resources to support you at gnucash.org and other places. Don't hesitate to use them.
gnucash.org
We have collected a bunch of useful information for you here in this wiki -
- navigate from the main page, or the Special:Categories or use the search function -
and on the website https://www.gnucash.org/.
And we have several channels of communication and a few other useful tools:
- IRC
- The fastest way to get help on simple questions is using the internet relay chat IRC, as many of the developers hang out there and are eager to help.
- Mailing lists
- Translators will probably find two or three gnucash mailing lists of interest. If you can not find the answers to your questions in their Mailing_Lists#Mailing List Archives, feel free to ask them.
- For language and region specific questions, where you should discuss terms and ask for proofreading of your work, use your languages mailing list. Currently we have
- gnucash-[pt_]br, de, es, fr, it, nl.
- If none exists for your language or nobody has an answer there, use the english lists:
- General use questions and answers are found on the gnucash-users mailing list,
- specific development questions go to the gnucash-devel list.
- If you dislike the heavy traffic on the above lists, you should at least subscribe the gnucash-announce list to get informed about new :releases.
- For language and region specific questions, where you should discuss terms and ask for proofreading of your work, use your languages mailing list. Currently we have
- To subscribe or view archives of these lists follow the links to the Mailing Lists.
weblate.org
Since 2020-12-14 the translations of some components, currently Glossary, Program and Website, are available at GnuCash @ Hosted Weblate.
- Requirement
- Only a web browser on your PC or mobile.
- Features
- Most pages of weblate have a help page behind the
?button. - Already as anonymous you can add suggestions and comments.
- After you created there an account, you can edit the translations.
- Tip
- If you also have a GitHub account and linked it there, we can give you some feedback on your contributions.
- If you already have been a GnuCash translator, tell us
- on irc://irc.gnome.org/gnucash (help about IRC) or
- by a mail to the gnucash-devel list your Weblate name to become a weblate/GnuCash reviewer there.
- Note
- We appreciate any help on the optimal configuration by experienced weblate users. You can contact the GnuCash team by irc://irc.gnome.org/gnucash or Mailing Lists.
Other Web Based Translation Tools
Several services for translation coordination exist, see Improve Localization Process#Web Based Translation Tools. As we have no experience with them contact the gnucash-devel mailing list before using them.
translationproject.org
The Translation Project coordinates the message cataloges of several programs
- Up to Gnucash 4.9 (2021-12)
- some of our translators had used it: last files. Most of them are now using Weblate.
Classical Direct Contribution
If you want to work on a new translation and you want to submit it directly to GnuCash, read on.
If you're starting a new translation it's much easier to begin with a tarball, which will include po/gnucash.pot; if you start from a Git clone you'll have to build Gnucash yourself first to generate gnucash.pot.
On Other Sites
- Technical Reference
- For many components we use the Gettext package. If you need help with msg* commands or the .po file format, read it's manual.
- General Translations Guidelines and Tips
- General information about how to approach the translation of software can be found here:
- Gnome
- As GnuCash is GTK based we follow their rules for consistency.
- In GNOME Human Interface Guidelines the most important section is writing-style, but also keyboard-input is of interest for the program.
- GNOME Documentation Style Guide V1.6
- https://wiki.gnome.org/TranslationProject
- https://wiki.gnome.org/TranslationProject/LocalisationGuide
- Other Useful Sites
-
- Often, but not always, https://en.wikipedia.org/wiki/ has a good explanation and proper language links for special terms.
- Comparing articles on wikipedia in your language and english can be helpful.
- There are many online dictionaries, use a search engine like google, to find the best fitting.
- An index of on-line dictionaries and a lot of other resources can be found at www.yourdictionary.com.
- In special cases the terminology database of the European Union Inter Active Terminology for Europe can be used, too.
How to submit changes directly to GnuCash
There are several options to contribute to the GnuCash translations:
Weblate
We recommend to use Weblate for existing languages as it has additional checks and other nice features compared to the pure gettext tools.
- Online
- One hour after you stopped editing it will create a commit on your behalf in its current pull request.
- Offline
- If you want to work offline, you can download the po file, edit it with your preferred editor, and upload it again. Weblate will then format it in the referred way before commiting it to its current pull request.
- Tip
- If you have a GitHub account linked to your weblate account you will get informed and can follow the process.
Pull Requests at GitHub
Pull requests are common for all parts which are not covered by weblate.
If you already are a github user you can publish your work as a separate branch on your gnucash[-{[ht]docs|on-windows}] fork and send a pull request to the GnuCash team. If you wish to continue your work before the request was completed, simlply create a new working branch. After the pull request was completed you can delete the related branch again. See Git for details.
- Commit messages
-
- Start your commit message with L10N:<LL>:
- were <LL>—or ${LL} below—is your language code.
- Append the intended improvement
- Example
- L10N:de: Update of SKR49 to official 2023 release
- Start your commit message with L10N:<LL>:
Verify the Result
After it got merged, you can …
- Website
- immediately open {https://www.gnucash.org/
- Program
- the next day download the (Linux) Flatpak or Windows nightly
to see and test the reslut of your work.
Obsolete Ways
Use they only if you have good reasons not to use one of the ways mentioned before!
Patches at Bugzilla
Before it was recommend to use Bugzilla. :
- Create an account if you still have none or login,
- create an request for enhancement bug against the Gnucash component translations, choose the version on which your patch is based and
- attach a patch
- containing the diff between the old files - if any - and your new files:
- If you have Git installed, the easiest way to create the patch is
git format-patch origin/stable..stable. - Else you can use diffutils:
diff -u[r] <original path> <modified path> > <name>.patch. Seeinfo difffor details.
- If you have Git installed, the easiest way to create the patch is
Mailing lists
You can simply email your completed message catalog (.po file) to the developers at the gnucash-devel mailing list. We'd really rather you use Github or Bugzilla because those are much less likely to get lost or forgotten, but if you really find those too hard we'll try to accommodate you on the list.
Translating the Program
To begin a translation you need either the message template file (gnucash.pot) if you're starting a new translation or the existing message catalog (xx.po or xx_YY.po, where xx is the ISO code for your language and YY the ISO code for a language-variant locale, see Naming Convention). These files are in the gnucash sources, which you can obtain either from our git repository or by downloading the latest release tarball from Sourceforge.
Get the source from Git
GnuCash uses Git as version control system. If it is new for you read An Introduction to Git.
The first thing to do is usually, to download the latest stable branch of gnucash from git and get it to build.[1]
Normally checkout the current stable branch:git clone https://github.com/Gnucash/gnucash ${SOURCEDIR}
cd ${SOURCEDIR}
git checkout stable
The argument ${SOURCEDIR} above can be whatever you want your local directory to be called, and is optional in the first line. If you leave it out, you'll have a directory called gnucash created containing all the source code below your current working dir.
Checkout the documentation (optional, but recommended):git clone https://github.com/Gnucash/gnucash-docs gnucash-docs
cd gnucash-docs
git checkout stable
Update your repository
After this initial git checkout, you can later update your local repository usinggit pull --rebase
from anywhere in the tree of ${SOURCEDIR}. We recommend to do it daily when you start your work.
Get packages, which are used while building
- Dependencies contains the list of packages, which are used while building GnuCash. If some are missing the configuration by cmake or the build by make or ninja will fail.
- For working on .po files we use several commands starting with msg. This are part of gettext-tools.
- Caution
- Gettext versions < 0.20 are known not to extract the 'developer_name' xml node, which contains the msgid "GnuCash Project". Do not remove this msgid!
- Optional
- Translate Toolkit is already used by Weblate and other projects. While gettext offers only a few formal checks Translate Toolkit has many quality checks in its pofilter command.
Under Linux use your package manager and install them.
Steps in the Build System
GnuCash uses the cmake build generator to control the build of all components. Details are described in Building. The following short-form instructions work on Unix systems and assume that you have already set up the dependencies according to the FAQ. If you are building the unstable or master branches you'll need to use your package manager to install two more development packages, boost-all-devel and googletest.
Build system generation
It's generally preferred to use a separate build directory. So let's set one up next to our source directory:cd /path/to/gnucash # replace the example path with your real source path
mkdir ../gnucash-build
cd ../gnucash-build
cmake -D CMAKE_INSTALL_PREFIX=../gnucash-install ../gnucash
This will set up a proper build system in the build directory based on the CMakeLists.txt file in the source directory. If generation fails or if you want to refine your build consult Building.
If all goes well you'll end up with a directory structure as follows:path/to/
gnucash/ # directory with gnucash sources
gnucash-build/ # directory to build gnucash and its translation in
gnucash-install/ # directory to install final result (not needed for development, just for completeness)
Compile
It is recommended that you compile the gnucash source code. It is a good idea to actually run gnucash with your new translations because it is quite helpful to see the phrases in the context of the running program.
Compilation is done by executing the make command in the build directory.
- Note
- Experienced users may prefer to use Ninja instead of Make. How to so is beyond the scope of this page.
cd ${BUILDDIR} # e.g. path/to/gnucash-build/
make
Run
GnuCash can be run from the build directory as follows:cd ${BUILDDIR} # e.g. path/to/gnucash-build/
./bin/gnucash # will open gnucash you just built
Note the use of './bin/' in the line to execute gnucash. This is to make sure you run the gnucash executable you just built rather than one that's installed by your distribution. Omitting this explicit path specification in the command will cause your system to launch
your distribution's pre-installed version of gnucash:gnucash # will open your distribution's pre-installed gnucash
In either case, you can easily switch between the various languages the gnucash has available by placing the LANG env var before the call to the executable. You can find details in Locale Settings.
Documentation
The GnuCash Help Manual and the Tutorial and Concepts Guide can use the same CMake build system as the code.
-
git clone gnucash-docsor unpack a gnucash-docs tarball - Using a terminal, go to your gnucash-docs directory
cd /path/to/gnucash-docs # replace the example path with your real path
- Make a build directory next to your source directory and go into it
mkdir ../gnucash-docs-build cd ../gnucash-docs-build - Configure the build system
cmake -D CMAKE_INSTALL_PREFIX=../gnucash-docs-install ../gnucash-docs
- These commands will set up a directory structure as follows:
path/to/ gnucash-docs/ # directory with gnucash-docs sources gnucash-docs-build/ # directory to generate gnucash-docs in various formats gnucash-docs-install/ # directory to install final result (not needed for development, just for completeness)
- These commands will set up a directory structure as follows:
- still in your build directory run
make html
${BUILDDIR}/share/doc/${LOCALE}/gnucash-guide/index.html
${BUILDDIR}/share/doc/${LOCALE}/gnucash-manual/index.html
where ${LOCALE} is one of C, de, it, ja, or pt (English, German, Italian, Japanese, or Portuguese respectively). You can use the file: URL scheme to point your browser to one of them; the links will work from there.
Naming Convention
The language code is of the following form:
- <language>[_<REGION>][.<Charset>][@modifier]
- using the well known ISO codes 639-1 for languages and 3166-1 for regions, which are in most cases countries .
- Only if no 2 letter code exists for your language in ISO_639-1, use the 3 letter code from ISO_639-2.
- If you are the first translator for your language, you should
- name your files and directories only with your language code.
- set Language: in the header of your po file with the full (language and region) code, if significant.
- So all people using your language despite of their region will benefit from your work.
- If there are parts, which are specific for your region, e.g. business account templates respecting local law, then they should be in a <language>_<REGION> directory.
- The common charset in gnucash is utf8.
- In the rare case different scripts are used for the same language like kyrilic and latin add for the less used the modifier e.g. sr@latin.
In the following parts of this document 'XXXX' and 'LL'—often prefixed by $ to mark them as variable—refer to your language code.
The glossary file
Inside the po/glossary/ directory should be a "glossary" file for your language. This file contains a bunch of commonly used terms found in GnuCash - and the explanation of a few very specific for GnuCash like the disambiguation between bill, invoice and voucher. It is recommended that you get this file translated first, and use it as a guide when translating the real .po file or the documentation. Please keep in mind that this file will never be visible to a user! The glossary file is only a tool for you, the translators! I repeat: The strings from the glossary file will never be user-visible, they are only used by you, the translator.
- Todo
- The current files have a very informal form. To make them more useful like conversion in tool specific glossary formats, we should replace by
msgid "generic term: term"
msgctxt "generic term" msgid "term"
- Go into the glossary directory:
cd po/glossary/ - If your .po glossary file does not exist or is older than gnc-glossary.txt, create the template:
./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot
- Create or update your language's glossary file:
- If your .po glossary file does not exist,
- use this gnc-glossary.pot file to create it with
msginit # add -l<locale> if different from your settings - Add your file into the set_dist_list(po_glossary_DIST ...) command in glossary/CMakeLists.txt to get it into the tarball.
set_dist_list(po_glossary_DIST CMakeLists.txt bg.po ca.po da.po de.po el.po es_NI-policy.txt es.po fr.po gnc-glossary.txt he.po hr.po hu.po it.po nb.po nl.po pl.po pt_BR.po pt.po ru.po rw.po sk.po sv.po txt-to-pot.sh vi.po zh_CN.po zh_TW.po)
- After changing CMakeLists.txt you have to rerun
cmake # add your options
- If your .po glossary file exists, but is older than gnc-glossary.txt use the msgmerge program to update it:
msgmerge --previous -U $LL.po gnc-glossary.pot;
- Now open your language's glossary file and translate it completely.
- Don't forget to #Check syntax and statistics of your .po file.
Terms missing or inadequate in the glossary file
If you detect an important term which is missing or could be better explained,
- create a pull request at github
- for the source file gnc-glossary.txt.
Msgid<TAB>Comment
- Reminder
- Does your editor enter <TAB>s or will it replace them with <Space>s?
To test it, run the following steps after you changed gnc-glossary.txt:
- To generate a new gnc-glossary.pot:
./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot
- run above msgmerge command for your LL.po,
- check and translate the new string in this updated glossary file.
- If successful, update all *.po files with:
for i in *.po; do echo -n "$i:"; LANG=C msgmerge --previous -U $i gnc-glossary.pot ; done #old form: find *.po -exec /usr/bin/msgmerge --previous -U '{}' gnc-glossary.pot \;
- Note
- The last step can also be done by a maintainer.
- LANG=C is only recommend for maintainers to get english error messages.
Get a fresh template
The Portable Object Template (.pot file) is a collection of all translatable strings.
It is important, to repeat this step e.g. after you asked a developer to change an insufficient string or you got an announcement about changed strings like commit messages starting with "I18N: " or containing a "[I18N]" flag.
- Tip
- If you have problems with this section, you download instead the "current template" from the translationproject.org. But keep in mind it is based on the last release and does not contain recent changes.
- If your repository is no fresh checkout, you should first #Update your repository:
git pull --rebase
- Only on the first run see Building to set up your build environment depending on your OS.
- Note
- As you can use make or ninja, on this page we write always make <target>. If you decided to use ninja, execute ninja <target> instead.
- Then in gnucash, a specific command at the top-level of the build tree (or source tree, if you do not use a separate build directory) will perform all necessary steps for this:
cd ${BUILDDIR} # adjust ${BUILDDIR} make pot
- If make complains
make: *** No rule to make target `<path/to/missing-source-file>', needed by `gnucash.pot'. Stop.there are obsolete relicts from a previous build. Just runmake clean # remove obsolete files make pot # try it again
- Now go into the po directory:
cd ${SOURCEDIR}/po # adjust ${SOURCEDIR}
If your language file already exists, continue with #Update an existing .po file.
Build a new .po file
If there is no .po file for your language, then you can start a new one. Start by
msginit [-lLL[_RR]] [-i<path/to/>gnucash.pot]
where LL is your language and RR your region code, if there is already a different LL.po like e.g. pt and pt_BR.
- -i<path/to/>gnucash.pot is required, if you use a separate build dir,
- -l... is only required, if your target is different from your environments current language.
This will initialize the meta information with values from your user environment.
- Notes
-
- msginit 0.21.1
- seems not to know languages spoken in and around India very well. Replace by
"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
—or whatever is right— in the new created file."Plural-Forms: nplurals=2; plural=n != 1;\n"
- msginit 0.19.3
- is querying an obsolete address of the translation project for language teams, but that doesn't matter.
If that does not work you can copy the file gnucash.pot into a work file named LL.po and just edit this file.
Adjust the header
Only if it was not created by msginit and updated via weblate the top of the .po file should be edited slightly.
- Header Comments
- The comments at the top of the file should be changed to be current:
# Indonesian translations for GnuCash package. # Terjemahan bahasa Indonesia untuk paket GnuCash. # Copyright (C) 2020 by the GnuCash developers and the translators listed below.# This file is distributed under the same license as the GnuCash package. # Triyan W. Nugroho <triyan.wn@gmail.com>, 2020. # […]
- Copyright
- Only files which were once maintained by the #translationproject.org should have a FSF copyright for that time range.
- Perhaps we should use and update a copyright year range?
- Translator List
- Weblate will expand the copyright comment by a list of
<Translator name> <email address>, year[ range]- in historical order. You can later copy the list into translator-credits ideally in reverse order.
- Conventions of your team (optional)
- This is also a good place to record typographic conventions, if more than one person work on the file:
# # Konventionen/Tastenkürzel: # »Zitate«: [AltGr]+{[Y]|[X]} # Gedankenstrich — [AltGr]+[Shift]+[-]
- Header Record
- The first, empty msgid "" contains information for you and the gettext tools. Each line of the msgstr contains a capitalized entry, a colon and a value. Replace all variables (uppercase words) with something appropriate. In this case, you will be the first author of the translation, and also the
- Last-Translator
- your name and email address, usually set by weblate. This person responsible for the recent change set, so we need an email address to contact you if there are issues.
- Language-Team
- Most languages are maintained by teams and everybody wants to get informed. That is usually the weblate language team. Before #translationproject.org or the german Gnucash translator team have been in use.
- If you are not using weblate enter the teams name and email address. If you are no member of a team, keep it empty or write
NONE.- Tip
- You can reuse this line in translator-credits.
- Language
- Already set by
msginitit should be the same as the filename without extension, usually the ISO code of your language. - Project-Id-Version
- <Package name> (set by
msgint) and <Version> (updated on msgmerges). - Report-Msgid-Bugs-To
- Should already been set by
msginittohttps://bugs.gnucash.org/buglist.cgi?roduct=GnuCash&component=Translationsor similar, where you can report issues with themsgids like- "There is a typo in <msgid>" or
- "<msgid> is impossible to translate to <your language> because of the grammatical difference …"
- if nobody reacts on your comments in weblate.
- POT-Creation-Date
- gets updated by
msgmerge. - PO-Revision-Date
- The timestamp of the last modification.
- Weblate and editors with a specific po mode should update it automatically.
- If you use a normal text editor, you will have to do it manually.
- Content Section
- Do not change but replace its older forms like
"MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n"
with the recent form."CHARSET: UTF-8\n" "ENCODING: 8bit\n"
- Plural-Forms
-
msginitshould have set it properly. E.g. many slavian languages have complexer rules than English's"Plural-Forms: nplurals=2; plural=n != 1;\n"
- See Gettext Manual: Translating Plural Forms for details.
- See the full explanation in Gettext Manual: Header Entry.
- Remove the `#, fuzzy' line once you have specified the items in capitals, because once this is done the header entry is no longer fuzzy.
Adjust special messages
- There is currently one special string:
#: gnucash/gnome-utils/gnc-main-window.c:4737 msgid "translator-credits" msgstr "" "Christian Stimming, 2001-2021\n" : "Jan-Uwe Finck, 1999\n" "\n" "Anregungen, Kritik und Fragen zur Übersetzung an die\n" "deutschsprachige GnuCash-Gemeinschaft <gnucash-de@gnucash.org>\n" "Um die Moderation zu vermeiden, empfiehlt sich die Anmeldung auf der\n" "<a\ href=\"https://lists.gnucash.org/mailman/listinfo/gnucash-de\">Liste " "gnucash-de</a>"
- This will appear in Help->About->Credits->Translation. So you should enter your name or that of your team and an email address where users can contact you for typos and gifts.
- Tip
- After some time more persons would have worked on the translation. Then you can expand it from your header comments to: If a list exists, we suggest to remove the email address of individuals for data protection reasons.
msgstr "" "<current translator>, <years>\n" "<previous translator>, <years>\n" : "<first translator>, <years>\n" "\n" "Send suggestions, critizism and questions about this translation to\n" "Klingon speaking GnuCash community <gnucash-tlh@gnucash.org>\n." "To avoid moderation we recommend to subscribe at\n" "<a # This comment exists only to trick the spamfilter. Rejoin the surrounding lines again. href=\"https://lists.gnucash.org/mailman/listinfo/gnucash-tlh\">List gnucash-tlh</a>" # Don't forget to replace Klingon (tlh) by your language and translate the rest!
Prepopulate your file with translations from your glossary and other projects
The basic idea is decribed in Gettext Manual: Using Translation Compendia. Your translator tools might already support compendia. If not, i.e you are using a plain text editor, here is the manual way:
There are in total 3 programms in use:
- msgcat
- Concatenates and merges the specified PO files.
- msgmerge
- Merges two or more Uniforum style .po files together.
- msgattrib
- Filters the messages of a translation catalog according to their attributes or manipulates their attributes.
- Example
- To merge a compendiumn like our glossary:
cd ${SRCDIR}/po # Gettext manual's suggestion to merge compendia without old po file: msgmerge --compendium glossary/${LL}.po -o ${LL}.po /dev/null ${BUILDDIR}/po/gnucash.pot # Perhaps better: msgmerge -U ${LL}.po --compendium glossary/${LL}.po ${BUILDDIR}/po/gnucash.pot
GOffice
Gnucash has borrowed a couple of source files from goffice. Those files contain a number of translatable strings. The goffice translation teams have already put effort in translating those in many languages. To reduce our translation effort, the script linked in I18N#Borrowing Code can be used to import these translations into our own po files.
If the goffice part for your language is incomplete, you might consider to offer them to update their file with your work.
GTK3
Stock buttons became deprecated in their version 3.10. They included:
- a label with mnemonic,
- for which the translation was already done in the gtk domain,
- a unique icon was associated.
So they are no longer used since gnucash 3.0. We use still the same labels, but the GTK translation is not directly used.
You can save some work by merging the po file of your language from GTK3, i.e. from https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/po into your gnucash po file.
- Example
- To merge fitting translations from GOffice and GTK:
#Example to merge common parts from po files in GOffice and GTK # Variant A: in single steps to watch their results ## 1. join 3. party translations msgcat --use-first -o tmp.po ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po ## 2. Remove unused messages. Authoritativ is gnucash.pot: msgmerge tmp.po ${BUILDDIR}/po/gnucash.pot | msgattrib --no-obsolete > {$LL}.po rm tmp.po # Variant B: in one command: msgcat --use-first ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po | \ msgmerge ${BUILDDIR}/po/gnucash.pot | \ msgattrib --no-obsolete > {$LL}.po
Adjust po/CMakeLists.txt
Also include your language code into the NEW_LINGUAS variable in the CMakeLists.txt file in the po folder of your source directory:# Set of available languages:
set (ALL_LINGUAS ar as az bg brx ca cs da de doi el en_GB es es_NI et eu fa fi fr gu he hi hr hu id it ja kn ko kok kok@latin ks lt lv mai mni mni@bengali mr nb ne nl pl pt pt_BR ro rw sk sr sv ru ta te tr uk ur vi zh_CN zh_TW)
CMakeLists.txt is a file, which controls the configuration of the build process. So after changing it, you have to rerun cmake. Some IDEs like Eclipse will do it automagical for you.
As part of the build your LL.gmo file is generated in the po directory of your build tree. Finally make install will copy it to the place, where it will be found at runtime. If you forget one of the steps, your translated language will not appear.
Continue with #Translating the .po file.
Update an existing .po file
Before you begin actual translation work, you should update the gnucash.pot file and use this to update your .po file. This process will insure that you have the latest translatable strings.
If your language file already exists, update it using the msgmerge program. This will move the old translations of unchanged strings in the new file:msgmerge --previous -U LL.po gnucash.pot
- Note
- If you had choosen a separate build directory, e.g. .build, adjust the path in above command:
cd ${SRCDIR}/po # adjust ${SRCDDIR} export BUILDDIR=../build # adjust this msgmerge --previous -U LL.po ${BUILDDIR}/po/gnucash.pot
- Separate commits for "noise" and real work
- You should now run git commit or create a patch "L10N:<locale>: Merge recent template".
- This will contain only the "noise" from the updated pot file as usually many line numbers change.
- Diff example after msgmerge
-
#. Business options -#: ../src/app-utils/app-utils.scm:303 -#: ../src/business/business-gnome/gncmod-business-gnome.c:117 +#: ../src/app-utils/app-utils.scm:322 +#: ../src/business/business-gnome/gncmod-business-gnome.c:119 msgid "Business" msgstr "Geschäft"
- Hiding your real changes in hundreds of such sections will make it really hard for your coworkers to find them.
After having done your translation you submit a second commit or patch containing your actual work "Update <locale>.po".
You should also do it, if your current translation tool uses other format settings like line breaks as the previous tool. In this case just open the file, save it and git commit or create a patch "L10N:<locale>: Preparation: Reformating".
- Example in KBabel format
-
#: ../src/app-utils/business-prefs.scm:33 msgid "The format string to use for generating customer numbers. This is a printf-style format string." msgstr "Используемая строка форматирования для создания номеров клиентов. Её формат соответствует printf."
- Example in PoEDit format
-
#: ../src/app-utils/business-prefs.scm:33 msgid "" "The format string to use for generating customer numbers. This is a printf-" "style format string." msgstr "" "Используемая строка форматирования для создания номеров клиентов. Её формат " "соответствует printf."
- Review the file header
- Project-Id-Version should be GnuCash 5.10 and
- <tt>POT-Creation-Date should be recent. If they are not, you probably forgot #Get a fresh template or #Updating an existing .po file.
- The PO-Revision-Date should be >= POT-Creation-Date.
Some, but not all tools will do this reliably for you.
Translating the .po file
Finally. You are ready to do some translating!
The .po source files are plain text files.
Tools
Some plain text editors offer a specific syntax highlighting for .po files, but there are also specific tools you can use:
- Emacs has a po-mode to edit po files.
- Geany, an editor with sytax highlighting and a little bit more
- GTranslator is another tool but we recommend not to use it because the version of 2006 doesn't support all of the interesting elements inside the po file. Update this, if you know it is fixed.
- Lokalize is the successor of KBabel since KDE4.
- Poedit to finish the PO file edit and build.
- POEditor can be used online.
- Pology is a Python library and collection of command-line tools for in-depth processing of PO files. Recommended in the Gettext Manual, but last released 2014-07-24.
- translate-toolkit is a python based suite. It is also used by sevices like weblate.
- Wikipedia:
(feel free to add more tools here)
Gettext source (.po) file format
Record Format
A record in a po file has the following form:<empty or only white-space>
# translator-comments
#. extracted-comments
#: reference…
#, flag…
#| msgctxt previous-message-context
#| msgid previous-untranslated-string
msgctxt optional-message-context
msgid untranslated-string
msgstr translated-string
- The empty or only white-space line is the record separator.
- In translator-comments you can put your own notes.
- The extracted-comments are notes from the programmers for you.
- One or more references tell you, where the message appears in the sources.
- The most important flags will be explained below in # Common Flags and source language format flag will be explained below.
- The previous-* entries will only appear, after msgmerge --previous … for fuzzy messages to show what changed.
- An optional-message-context has the purpose to distinguish equal msgids with different meanings.
- The msg* should explain themself above.
- Example
- Here is an example of translating some text into German:
- Before
-
#: messages-i18n.c:11 msgid "" "The GnuCash personal finance manager.\n" "The GNU way to manage your money!" msgstr ""
- After, the translation in the de.po file
-
#: messages-i18n.c:11 msgid "" "The GnuCash personal finance manager.\n" "The GNU way to manage your money!" msgstr "" "GnuCash: Ihr persoenlicher Finanzmanager.\n" "Der GNU-Weg, ihr Geld zu verwalten!"
You should read through every translation in the .po file at least once.
Common Flags
Fuzzy Flag
If you see a string that has the phrase #, fuzzy in the flags comment above it, review the translation and confirm it by removing
- the , fuzzy flag, but no other flags like , c-format,
- the #| msgid lines, and in some cases
- the #| msgctxt line.
A fuzzy translation means that the translation will be ignored by the program.
There are at least 2 reasons for the fuzzy flag:
- one of the msg* programs took some guess about what the translation might be from similar msgids,
- in a previous version you had a valid translation, but a programmer changed (parts of) the msgid.
cd ${SOURCEDIR}/po
msgattrib --fuzzy ${YOUR_LANGUAGE}.po
- Example fuzzy message
- Here the msgid was changed from "opening" to "writing". You need to correct the translated string, remove the line(s) with the old msgid "#| msgid …" and the 'fuzzy' flag, because only then the translation will actually appear in the program.
#: messages-i18n.c:35 #, fuzzy, c-format #| msgid "There was an error opening the file %s." msgid "There was an error writing the file %s." msgstr "Es gab einen Fehler beim Oeffnen der Datei %s."
- Example fuzzy fixed
- Notice that #, c-format was not removed. That is correct, you should leave that.
#: messages-i18n.c:35 #, c-format msgid "There was an error writing the file %s." msgstr "Es gab einen Fehler beim Schreiben der Datei %s."
- Tip
- If all fuzzy strings were fixed (
msgattrib --fuzzy $LL.poreturns nothing), you can also bulk remove the previous messages withmsgattrib --clear-previous -o $LL.po $LL.po
Format Flags
Because parts of GnuCash were written in different programming languages, there appear at least 2 different format flags:
- c-format
- Format specifier:
% - When you see the comment "c-format", it means that the format codes in the translatable string are referring to C formatting codes. So, '%s' means text, '%d' means an integer, etc...
- scheme-format
- Format specifier:
~ - Todo
- Which parts of #Special_characters_and_other_tips would better stay here?
Orphaned Records
At the end of your file you might see records like#~ msgid "Enter an Online Direct Debit Note"
#~ msgstr "Online-Lastschrift eingeben"
#~ msgid "Debited Account Number"
#~ msgstr "Konto-Nr. des Zahlungspflichtigen"
They have no reference line. This records are no longer in use and you can remove them.
Translate the strings
Each message to translate is then given in turn in the PO file. For example, an untranslated entry might be:#: lib/error.c:88
msgid "Unknown system error"
msgstr ""
#: lib/error.c:88
msgid "Unknown system error"
msgstr "Unbekannter Systemfehler"
You just produce a translation for all entries in the PO file, one after another, respecting the overall file format and the quoting needed for special characters, when needed. Observation and intuition may allow you to grasp what the format should be; the precise rules for PO files are given in the GNU gettext manual. The msgfmt program is helpful for pinpointing formatting errors.
Contexts
- Important
- With Gnucash 3.7 the first 2 forms got replaced by #Message Context. The description of the old types is only kept for some time to help updating older catalogs.
At some places, GnuCash uses "disambiguation prefixes" in translatable strings. Here is an old explanation: https://lists.gnucash.org/pipermail/gnucash-devel/2005-October/014236.html ; more explanation is also here: https://wiki.gnome.org/GnomeI18nDeveloperTips.
There are at least 2 use cases:
- Abbreviations, i.e. for columns and their headers:
msgid "Reconciled" msgstr "Abgeglichen" : msgid "Reconciled:R" msgstr "Reconciled:A"
- Sample text to determinate the size of the output cell. Instead of a translation the "worst case" of expected text in your language is required here.
- For the following example the german tranlators copied the longest path of account names from their business account templates as shown in the accounts tab of Gnucash:
msgid "sample:Expenses:Automobile:Gasoline" msgstr "sample:Aufwendungen 2/4:Reparatur/Instandhaltung:4805 Reparatur u. Instandh. von Anlagen/Maschinen u. Betriebs- u. Geschäftsausst."
- Important
- Keep the part before the colon untranslated.
#. Translators: This string has a context prefix; the translation
#. must only contain the part after the | character.
#: gnucash/gnome-utils/dialog-options.c:722
#: gnucash/gnome-utils/gnc-tree-view-account.c:908
msgid "Column letter for 'Placeholder'|P"
msgstr "P"
#: gnucash/gnome-utils/dialog-options.c:719
#: gnucash/gnome-utils/gnc-tree-view-account.c:906
msgctxt "Column header for 'Placeholder'"
msgid "P"
msgstr "P"
- Tip
- A tool like kdiff3 can help you to recover your previous translation.
Message Context
In more recently written parts we use a message context:#: libgnucash/app-utils/gnc-ui-util.c:903
msgctxt "Reconciled flag 'not cleared'"
msgid "n"
msgstr ""
Special characters and other tips
Depending on the context a few characters have a special meaning and need some special treatment:
- "#" (hash)
- In English it is often used as abbreviation for "Number". You should replace it by "No.", "Nr." or whatever is common in your language.
- "_" (underline)
- In menu and dialog entries the following character will become the accelerator, mnemonic or hotkey, which can be used together with a superkey
ctrloraltto jump to the entry. While in GTK2 they have always been visible, in GTK3 they appear only after holding the superkey. More specific under Linux you reach a main menu entry withalt+<key>and its submenus and other menu entries with<key>. In dialogs always usealt+<key>. - The terminology is not unique here: while
- msgfmt has a --check-accelerator option and
- DocBook uses the <accel> tag for a letter used with a meta key and <shortcut> for a key combination, but
- GTK+ distinguishes the underline marked character of the label as mnemonic and the hotkeys like
F1for Help orctrl+cfor Copy as accelerator.
- So the key should
- exist on a keybord for your language.
- be easy to remember for your users,
- be unique in its context and you should control it by #Running GnuCash with your file after #Compile & Install. See also Access Keys in Gnome's HIG about keyboard input.
- wrong:
- "do _this" # Hotkey: t
- "do _that" # Hotkey: t => not directly reachable
- "do th_is" # Hotkey: i => thin letter, underline becomes invisible
- right:
- "do thi_s" # Hotkey: s
- "do th_at" # Hotkey: a
- That is one of the reasons why you should run the program with your translation: to see duplicate accelerators.
- Characters to avoid
- In dialogs some are already used on buttons like in English:
Close,Help. Others depend on the context. - Thin letters like lowercase i or l, because the underline is to short.
- Characters breaking the baseline like in latin script: j,p,q,y. At least in some fonts the underline becomes invisible - leaving the user clueless.
- wrong:
- It is not required to use the same key as in English, Example from de.po: Languages are just different.
#: gnucash/gnome-utils/gnc-main-window.c:273 msgid "_File" msgstr "_Datei"
- In Weblate
- Compare https://hosted.weblate.org/browse/gnucash/gnucash/$LANGUAGE/?offset=1&q=_&sort_by=source&checksum=, but replace
$LANGUAGE
by your language code.
- "\" (backslash)
- It is the escape character in many programming languags. The following character has a special meaning like e.g.:
- "\n" (New line)
- The most often used special character in our strings. If msgid contains "\n" keep the layout and add them to msgstr too - at the same places.
- "some \"quoted\" text"
- Because " terminates the messages, you must precede it by a backslash inside of the messages or use other quoting characters like:
- "some 'quoted' text"
- "some »quoted« text"
- "some „quoted” text"
- You are free to use the conventions which are common or suggested in your language, but stay consistent. For that purpose you should add a translator comment about the convention at the beginning of the file for better cooperation.
- Use "\\" to print a backslash.
- "%" (percent)
- In C based programming languages "%" marks the beginning of a format specifier, e.g. "%d6" means insert the next variable here in decimal format with 6 digits. Such format specifiers should be copied into your translated message, at the appropriate spot for your language, see https://www.boost.org/doc/libs/release/doc/html/date_time/date_time_io.html#date_time.format_flags Boost's list of format flags for date and time].
- Non-ASCII digits
- As a special feature for Farsi (Persian) and maybe Arabic, translators can insert an ‘I’ flag into numeric format directives. For example, the translation of "%d" can be "%Id". The effect of this flag, on systems with GNU libc, is that in the output, the ASCII digits are replaced with the ‘outdigits’ defined in the LC_CTYPE locale category. On other systems, the gettext function removes this flag, so that it has no effect.
- Note
- If a string is marked with c-format and has a % mark that does not start a format specifier, file a bugreport and tell the developers the location of the string (the lines above the msgid). The developers should fix this in the code. One way to do so is to insert a comment containing xgettext:no-c-format before the gettext call.
- In order to continue without having to wait for the developers' fix to propagate you can remove the c-format flag from the #, comment line above. If no other flags are in the line, simply remove the line.
- To output "%" if a string contains format specifiers, use "%%" in your string.
- Reordering parameters
- Assume a string "In %d cases the result will be %d.", but in your language you would prefer to write "%d will be the result in %d cases." Now you would get the wrong numbers.
- Solution
- Insert the ordinal number of the parameter, followed by "$" in the format specifier: "%2$d will be the result in %1$d cases.".
- "~" (tilde)
- like "%", but for scheme-format. The basic scheme-format uses ~a or ~s to format subsequent variables within code and should be copied in the translated message, in the same order. Guile's (ice-9 format)[2] does reordering with the ~@* and ~#* arguments, but it's a bit tricky to use: would print
(format #t "~@*1~a's ~@* from ~@*2~a to ~a" "Balance Sheet" "Yoyodyne Pty" "1 Oct 2018" "30 Sept 2019")
Yoyodyne Pty's Balance Sheet from 1 Oct 2018 to 30 Sept 2019- Note
- ~a will insert a contents using "human readable" (display var) whereas ~s will insert contents using (write var). This is an important difference which means ~a and ~s cannot be interchanged.[3]
- "{num,optional other specifiers}"
- this is a format specifier for C++ code. You cat either copy it verbatim somewhere in your translated message or you may adapt it to your language.
- "$" (Dollar)
- Since 2023 there is another format specifier: ${parameter-name}.
- Example
- will print
(gnc:format "${start} to ${end}" 'start "1 Oct 2018" 'end "30 Sept 2019")
[4]1 Oct 2018 to 30 Sept 2019
- "&" (ampersand)
- is the starting character of HTML encoding, which is used in some reports. E.g. means NonBreakableSpace.
- "<" (less)
- is the starting charcter of tags in several markup languages. E.g. results in bold Text.
<b>Text</b>
- See also
- GUI Guidelines is the related programmers view.
Almost Done
If you are almost done it becomes harder to find the last untranslated messages. Then you can usemsgattrib --untranslated ${LL}.po
Check syntax and statistics of your .po file
- Required
-
msgfmt -c --statistics ${LL}.po
If that program reports one or more fatal errors for your language, you should review the criticized lines of your file.
- Tip
- A successful call will create a file messages.mo. If you are not using a build environment, you can move that file to
- Linux
- ${PREFIX}/share/locale/${LL}/LC_MESSAGES/gnucash.mo
- and restart gnucash to test the program with your translation.
- Desired
- In a second run you might wish to see, where you forgot to add an accelerator:
msgfmt -c --check-accelerators="_" --statistics ${LL}.po
The users will love you if you fix them, too.
Current status
To see some over all statistics how many strings are translated, you can run
for i in *.po; do echo -n "$i:"; msgfmt -c --statistics $i;done
in your po directory.
Priority
As you might have noticed, the po file for GnuCash is rather big by containing more than 4000 strings. It is somewhat helpful to look into different priorities for the different strings there. However, unfortunately the po file format doesn't enable any easy way for the GnuCash project to make the import strings differently from the less important ones. However, for a few files the developer team can give you some guidelines for the general priorities.
The source code location aka ref[erence] of a string gives you some hint about its priority. In particular, the following file suffixes or file locations imply a certain priority:
- High Priority: Strings from all *.glade files will be presented by the GnuCash user interface (UI) somewhere for the user. This may imply a somewhat higher priority to those strings - however, some UI elements are rarely used, so the actual location of the .glade file has an influence as well, but there isn't an easy rule for that anymore.
- Tip
- If you wish to see the string from a *.glade file in it's context, but don't know, where it is hidden in gnucash, if
- the gnucash source files and
- the Gnome's interface builder Glade
- are installed on your system, you can preview them for instance with [5]
LANG=C glade-previewer -f ${SOURCEDIR}/gnucash/gtkbuilder/${FILENAME}
- Low Priority: Strings from all *.schemas.h files will not appear in the gnucash UI. Instead, they are shown only inside the
- Linux: dconf-editor,
- macOS: defaults or
- Windows: regedit program when the user wants to set particular GSettings keys of GnuCash. You can safely consider the .schemas.h strings with lower priority than the others.
- Register2 feature is a stalled developement. The strings are only visible, if you #configure --enable-register2. Some, but not all strings are marked with a "Register2 feature" comment.
Unfortunately, there is no such simple rule for strings from *.c files or the single large intl-scm/guile-string.c file. The strings from there may be of higher or lower priority, but this isn't easily visible. We can only recommend to start GnuCash on your own with your updated translation, and then check for strings which you see but are not yet translated. Those are for sure of high priority.
Two additional source code locations can be noted as low priority:
- Everything from the file src/bin/gnucash-bin.c is of low priority because those are the command line options when running gnucash with different options from the command line. This is a use case that is performed only by highly experienced users which are accustomed to using the English-language command line commands. Therefore, translations here are of lower priority.
- Everything from the folder src/tax or from the intl-scm/guile-string.c file with a comment indicating some file in src/reports/locale-specific is related to tax preparation in the U.S. or in Germany. Hence, those strings are uninteresting for anyone living in different countries, and you can safely consider those with very low priority.
Testing and submitting your translations
You must check that your new translations are programatically correct (ie:
that there are no unclosed quotes, etc). To do this, use the msgfmt programmsgfmt -c --statistics $LL.po
Above call will report most important errors in your .po file and must not fail, while the call below
msgfmt -c --check-accelerators="_" --statistics LL.po
whill additionally check if you missed some keyboard accellerators aka hotkeys.
- Note for developers
- Another python based tool is i18nspector - checking tool for gettext POT, PO and MO files. It is stricter and shows also warnings about expected entries which our .pot file is currently missing. That can be discussed e.g. in #Background.
If you want to see your translations within a running version of gnucash, simply place your .po file in the po/ directory of your local gnucash source repository (which you have previously installed) and a regenerate your message catalogs with:
cd ${BUILDIDR} # adjust to navigate to your build directory
make po-gmo
Now you can run gnucash with your new translations:
cd ${BUILDIDR} # adjust to navigate to your build directory
LANG=XXXX ./bin/gnucash
To review the schema strings you can use 'dconf-editor'
Alternative Way with Poedit
If you use Poedit while working on .po file, you would notice that it saves file in .mo format, the very format that GnuCash uses itself. So one would just need to copy this LL.mo file into appropriate subdirectory of your build directory:
cp ${LL}.mo ${BUILDDIR}/share/locale/${LL}/LC_MESSAGES/gnucash.mo # replace ${BUILDDIR} with the actual path to your build directory
The only thing that needs to be changed here is <LL> which stands for your language code (ka Georgian, de German etc). The rest is as in above method:
cd ${BUILDDIR} # adjust to navigate to your build directory
LANG=$XXXX ./bin/gnucash
Submitting
just push your commit (Git#Pull Requests) or upload the Git#Patches of the files. There should be one commit/patch containing the noise as described in #Update an existing .po file and a second one containing your actual work.
Then follow #How to submit changes directly to GnuCash. See also https://lists.gnucash.org/pipermail/gnucash-devel/2009-January/024700.html [FIXME: obsolete?]
Committers
- Did you get #The glossary file, too?
- Ideally #Updating an existing .po file
- Checks:
- Notify the statistics for the commit message.
- The Python tool i18nspector finds many additional errors, particular bad header lines. But its language list is incomplete as it knows not many 3-letter-languages.
- Some common mistakes:
- msgid "translator-credits"
- should contain at least the "Last-Translator:" from the header.
- msgid "gnucash-icon"
- do not translate, we have only one.
- If the language is new
- #Adjust po/CMakeLists.txt already done?
- On committing add the name and email address of the last translator from the file as author, e.g.
git commit --author="Lieutenant Worf <lt.worf@starfleet.org>" --message="L10N:tlh[: optional status or other details] 4677 translated messages." # << The msgfmt statistics
- If you check in a new language, remove a language or see the status of the language changes from partial to (almost) complete, update the numbers in <sect2 id="oview-featuresintl2"> in file guide/C/ch_oview.xml of gnucash-docs.
Problems
Gtk-CRITICAL messages
Note: Fixing this problem is quite difficult. We keep the explanation here in case some developers need it in the future, but if you have no idea what we are talking about in the next sentences, you should rather ignore these Gtk-CRITICAL messages and our explanation here!
If you see any "Gtk-CRITICAL" messages while running gnucash, it is probably because you translated a string differently than how it exists in some other gnome library. You must discover which string you translated differently, and change the translation to exactly match that of the gnome libraries.
To do this, you need to run gnucash under gdb:
cd ${BUILDIDR} # adjust to navigate to your build directory
LANG=§XXXX gdb ./bin/gnucash
run --g-fatal-warnings
Eventually, gnucash should crash (because of the --g-fatal-warnings
directive), when it does, issue from within gdbbacktrace
#0 0xffffe002 in ?? ()
#1 0x42028a73 in abort () from /lib/tls/libc.so.6
#2 0x4019d3d8 in g_logv () from /usr/lib/libglib-1.2.so.0
#3 0x4019d414 in g_log () from /usr/lib/libglib-1.2.so.0
#4 0x40500fdd in gtk_type_check_object_cast () from
/usr/lib/libgtk-1.2.so.0
#5 0x407292e5 in gnc_mdi_tweak_menus (mc=0x825adb0) at gnc-mdi-utils.c:574
#6 0x40729d13 in gnc_mdi_child_changed_cb (mdi=0x8266fd8, prev_child=0x0,
data=0x8265fd8) at gnc-mdi-utils.c:861
Notice position #5 which has "gnc_mdi_tweak_menus at gnc-mdi-utils.c:574"? Open that source file and find line 574:
573 widget = gnc_mdi_child_find_menu_item(mc, "_View/_Toolbar");
574 gtk_signal_handler_block_by_data(GTK_OBJECT(widget), info);
So, the problem is with the translation of "_View/_Toolbar". The "/" is a menu seperator, so you now know that the problem is with either the translation of "_View" or "_Toolbar". By switching to an English gnucash (LANG=C) and looking through your .po file, you should be able to find out the problem. Change the offending translation to whatever you see in the gnucash app. Remember that the translations must contain the proper underscores.
Watch File accesses
To follow gnucash as it access filesstrace /opt/gnucash-git/bin/gnucash
Check Files in Repo gnucash's doc Directory
- Note
- The content of this directory got some cleanup by
bug 797111.
In theory one could create localized man pages (<command>.<man-section>[.in]). But their content is almost the same as <command> --help, which are translated for gnucash and gnucash-cli.
- Task
- We should use gettext also in the perl modules.
- If you add files add them to set(doc_DATA ...) in CMakeLists.txt.
Translating the GnuCash Manual and Guide
Moved to Documentation Translation.
How to translate the files containing the new account hierarchies
This section describes the actions needed to translate the files containing the new account hierarchies.
Preliminary Considerations
- However, please take a moment to think about the intention of the account hierarchy templates. The intention of those files is much more language-related than any other of the files inside gnucash. A string-by-string translation is not the best thing to do here. Instead, you can and should find out an actual recommended account structure which makes sense in your language, and implement that one in your language. By this, I mean several of the english accounts make sense only in the U.S., but probably not in other countries. Hence, your translated account template should not contain them. Also, you can add additional parts of the account templates for your language as well, if the users are likely to need it.
- For example, in the U.S., users are likely to own a car, and for this reason there is an account structure template for "Car". If in another hypothetical region users are likely to own, say, a spaceship instead of a car, you should remove the "Car" template and instead create a new account structure that represents all accounts related to the ownership of a spaceship, and offer this as additional "Spaceship" template.
- In other words, you should feel free to create a completely new account template structure that is most suited to your language. The english-language templates are just a proposal, but will need further adaption and not a string-by-string translation.
Having said that, here is how you would start for a direct translation of the English templates:
In this section always replace <locale> with your language code and optional your region code, if there are multiple countries with the same language and your templates are fitting only to one of them.
Prerequisite
- If not done before, #Get the source from Git.
Initialize accounts/<locale>
- If it does not already exists, execute the following steps to initialize your accounts/<locale> directory:
- Copy the directory accounts/C to accounts/<locale>.
- Tip
- If there is already a directory in your language, but for a different region you can instead also copy that.
- In the directory accounts/ change the file CMakeLists.txt and add your <locale> to both alphabetical sorted lists:
-
add_subdirectory(C) : add_subdirectory(<locale>) :
-
set(accounts_DIST ${C_DIST} ... ${<locale>_DIST} ... ${dist_list} PARENT_SCOPE)
-
- In accounts/<locale>/CMakeLists.txt adjust the <locale>:
: set_dist_list(<locale>_DIST ${dist_account_DATA} CMakeLists.txt) install(FILES ${dist_account_DATA} DESTINATION ${ACCOUNTS_INSTALL_DIR}/<locale>) file(COPY ${dist_account_DATA} DESTINATION ${ACCOUNTS_BUILD_DIR}/<locale>)
- Note
- The next 2 steps are are discussed in #Localize the Account Charts below.
- Localize acctchrt_full.gnucash-xea. This is only a helper file where you have all accounts in their context.
- Now create the real modules by merging the respective parts from acctchrt_full.gnucash-xe in the other acctchrt_*.gnucash-xea files.
- If you remove or create new files, adjust in accounts/<locale>/CMakeLists.txt the list
set(dist_account_DATA ...)
- Whenever you changed one or more CMakeLists.txt files, you have to rerun
cd ${SOURCEDIR} cmake <your options> cd ${BUILDDIR} # e.g. .build make # or ninja
Localize the Account Charts
Tip: C/acctchrt_full.gnucash-xea is a helper file. Because we prefer modularization it usually is not part of the distribution. It contains the full tree of the personal en_US accounts. The other acctchrt_*.gnucash-xea files contain single branches of that. So after translating it you can copy&paste the respective parts in the other files to ensure consistency between them.
If you modularize the templates you should start with acctchrt_common.gnucash-xea - it is the most basic.
For each desired acctchrt_* file in that directory:
- Change the gnc-act:title, gnc-act:short-description, and gnc-act:long-description to contain appropriately translated text. Do not add any newlines in the long description except at the end and begining of the string.
- For each gnc:account in the file
- translate the act:name, and act:description fields.
- Optionally you can
- assign an account number <act:code>1234</act:code> after <act:commodity-scu> or
- add a note as i.e. in
<act:slots> <slot> <slot:key>hidden</slot:key> <slot:value type="string">true</slot:value> </slot> <slot> <slot:key>notes</slot:key> <slot:value type="string">Some additional text about the usage of this account</slot:value> </slot> <slot> <slot:key>placeholder</slot:key> <slot:value type="string">true</slot:value> </slot> </act:slots>
- Please do not translate any other fields or the internally used ROOT account.
- To avoid typos, run the Account Hierarchy Template#Syntax Check.
- New files to be shown to the user must be added to the account_DATA section,
- helper files like acctchrt_full.gnucash-xea to EXTRA_DIST in Makefile.am.
Note again: You absolutely don't need to translate all of the files from accounts/C. A subset of those are fine as well. Probably several of them will not apply to your local legislative/economic system anyway. For a really customized account hierarchy you might better create a new account hierarchy file in GnuCash, and then, by hand-editing the xml code, split it up into several files and cut&paste the appropriate tags from the accounts/C/acctchrt_* files.
If you wish to add new accounts manually, you will need some additional guids, those funny random numbers. To get them you can use:uuidgen | sed -e 's/-//g'
or use an online uuid generator like this one (any other one will do as well). Be sure to untick "Hyphens" to generate gnucash compatible guids. If you forget or the site you use doesn't offer that option, simply remove the hyphens yourself.
- Dependencies
- uuidgen is in a package 'util-linux', sed has its own package.
Account Hierarchy Template describes, how to create new templates e.g. for business purpose according local rules.
Test your Work
To test your work under real conditions, you should finally Compile & Install it. But before you need an adjusted Makefile.am in your accounts/<locale> directory. If none exists, copy that from accounts/c and adjust it:
- 1. Line (accountdir): adjust the locale.
- If you removed accountcharts, remove their line from account_DATA,
- if you added new files, insert lines with their names and "\" (the line continuation symbol).
How to create localized Income Tax Tables
- Note
- This section is under developement and mostly untested!
As of the beginning of 2015 there is a nice US tax module, with a report and export in TXF format, and a small German (de_DE) derivate for the monthly VAT declaration. You can compare them to see how you can tweak them to get something else.
Tax Table
Because it is also used by Edit->Tax Report Optionsit is part of the GnuCash library:
- Copy us into a new subfolder with the lowercased ISO code of your region.
- It contains the following files
- tax.scm - is only a linking element, where you have to replace us by your region twice.
- txf.scm - the tables, and
- txf-help.scm - the descriptive help strings for each TXF code. This is also used to get a table in gnucash-docs/help/
- They have relative simple table structures:
(define txf-tax-entity-types
- contains a list of forms for different entities (person, company …).
(define txf-income-categories … (define txf-expense-categories …
- contain for each of the above lists the entries. If you compare this file with the respective files in de, you can see an example localization with additional categories:
(define txf-asset-categories … (define txf-liab-eq-categories …
- It should be possible to adapt the lists for your tax forms.
- contains a list of forms for different entities (person, company …).
Report and Export
Probably you need to have other export reports. That are in https://github.com/Gnucash/gnucash/tree/stable/gnucash/report/reports/locale-specific/us like
- txf-export.scm
- us.scm is unused
Here you might probably need some help from a programmer.
How to translate the website
- Note about OS
- These instructions are written for linux. They will probably work on other unix-like systems as well, but not on Windows. On Windows you may be able to do this if you set up a linux-like environment (with cygwin or MinGW[-w64]), but that's untested so far. Please report your findings here.
- Get a checkout of https://github.com/Gnucash/gnucash-htdocs
- Run the command
make pot
- Then depending on whether or not a translation for you language exists already (complete or not):
- Existing translation
Run the commandwhere LL is your language code, see #Naming Convention above.msgmerge --previous -U po/LL.po po/gnucash-htdocs.pot
- Alternative
- will update all .po files
make msgmerge
- New translation
In the po directory run- As translator
- This will insert your name, email and locale settings into the new file. If that fails copy the newly created file po/gnucash-htdocs.pot to po/LL.po, where LL is your language code, see #Build a new .po file earlier.
msginit
- As maintainer
- This will create a new file $LL.po without personal data. Continue with #Maintainers Task.
# Set LL=<language code> msginit --no-translator --locale=$LL
- Translate the po/LL.po file as described in #Translating the .po file.
- Priority
- High
- Startpage: {index|externals/*}.phtml
- Low
- sizing.phtml (outdated) search/templates/NMZ.* (unused)
- Medium
- the rest depends on you.
- Run to see your success.
msgfmt -c --statistics po/LL.po
- Optionally run to get special characters HTML quoted.
recode -d <input_encoding>..h0 po/LL.po
- Send your LL.po either as
- GitHub Pull Request or
- attachment of a Bugzilla enhancement request to the mainteiner team.
Background
This section was started to get some overview, work in progress! Beyond it helped to get rid of the outdated #IntlTool in version 2.7.6. For details see the GetText Manual.
Packages
In our build process we use beneath self written scripts the following packages:
- glib2-devel: glib-gettextize
- gettext, probably broken in:
- -runtime: msgfmt, ...
- -tools: (autopoint), gettextize, msg*, xgettext, ...
- -runtime-tools-doc: manuals etc.
- (only up to 2.7.5) intltool: Intltool*
Our Build Process
This was the old (upto 2.6) autotools build process, which went through the following scripts:
autogen.sh
- Note
- Autotools were only used up to 2.6 branch. 2.7 and later use CMake instead.
- glib-gettextize
- helps to prepare a source package for being internationalized through gettext. It is a variant of the gettextize that ships with gettext.
- glib-gettextize differs from gettextize in that it doesn't create an intl/ subdirectory and doesn't modify po/ChangeLog (note that newer versions of gettextize behave like this when called with the --no-changelog option).
»Note that on GNU systems, you don't need to link with libintl because the gettext library functions are already contained in GNU libc.« (glibc) [1].
configure.ac
- Sets
ALL_LINGUAS= ...
In recent versions it can be substituted by LINGUAS files in the po directories. We should consider this to distinguish TP vs. GC maintained translations.
GETTEXT_PACKAGE=gnucash
This is intltool style. Gettext uses PACKAGE=...
AC_SUBST(GETTEXT_PACKAGE) AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, "$GETTEXT_PACKAGE", [GetText version number])
AM_GNU_GETTEXT_REQUIRE_VERSION|AM_GNU_GETTEXT_VERSION(x.yy.zz) can be used to require a version. We should use it to avoid ...
- TP expects > 0.11.
- gnulib expects >= 0.17
- RHEL7 offers 0.18.2 (RHEL6 0.17)
- Debian Stable offers 0.18.1 and in backport 0.19.3
- Glade2 msgctxt and Glade3 were implemented in 0.18.3 - July 2013
- GSettings and Desktop entries are implemented in 0.19 - June 2014
- and got bugfixes until Version 0.19.3 - October 2014
- Scheme format strings got a fix in 0.19.4 - December 2014
- AppData support: gettext-0.19.6 released - 2015-09
- ? custom XML formats in 0.19.7
- <gjanssens> GtkUIManager files don't contain translatable strings as far as I know. They're not in POTFIILES.in either.
- at the time of our last update: gettext-0.19.8.1 released - 2016-06
- gjanssens sv->swedish patch for Windows is in gettext 0.20. It is also the first version , which extracts <developer_name> from appdata.xml. IRC log
- recent: GNU gettext 0.20.1 released - May 12, 2019
This setting then can be used by autoPoInt. Watch the caveaets from https://www.gnu.org/software/gnulib/manual/html_node/gettextize-and-autopoint.html:
- On the other hand, if your package is not as concerned with compliance to the latest standards, but instead favors development on stable environments, the steps are:
- Determine the oldest version of gettext that you intend to support during development (at this time, gnulib recommends going no older than version 0.17). Run autopoint (not gettextize) to copy infrastructure into place (newer versions of gettext will install the older infrastructure that you requested).
- Invoke gnulib-tool, and import the gettext-h module. # Fixme: Meaning?
- Regardless of which approach you used to get the infrastructure in place, the following steps must then be used to preserve that infrastructure (gnulib’s bootstrap script follows these rules):
- When a script of yours run autopoint, invoke gnulib-tool afterwards.
- When you invoke autoreconf after gnulib-tool, make sure to not invoke autopoint a second time, by setting the AUTOPOINT environment variable, like this:
$ env AUTOPOINT=true autoreconf --install
AM_GLIB_GNU_GETTEXT # FIXME: Meaning?
- runs checks with settings
- AC_PROG_INTLTOOL
- AC_CHECK_HEADERS(ltdl.h, ...
dnl Make sure we have a proper gettext installed AC_MSG_CHECKING(for a valid gettext/gmsgfmt installation) if test "$gt_cv_have_gettext" != "yes" || test "x$GMSGFMT" = "x"; then AC_MSG_RESULT(no) AC_MSG_ERROR([Cannot find Glib Gettext. Maybe you need to install the gettext package?]) else AC_MSG_RESULT(yes - $GMSGFMT) fi
makefile.am
has the following section:
.PHONY: pot
pot: Makefile po/POTFILES.in
rm -f po/$(PACKAGE).pot
${MAKE} -C po $(PACKAGE).pot
$(srcdir)/po/POTFILES.in: make-gnucash-potfiles .potfiles
if test -w $(srcdir)/po/POTFILES.in ; then ./make-gnucash-potfiles > $(srcdir)/po/POTFILES.in ; fi
# Creation rules so that po/gnucash.pot can always be created for
# make dist.
po/gnucash.pot: po/POTFILES.in
${MAKE} -C po gnucash.pot
.potfiles:
make-gnucash-potfile.in
This is a self written perl script from the time as gettext had several issues. It creates po/potfiles.in, the "list of files which contain translatable strings". This script is not used in a cmake based build environment for gnucash. As gnucash 2.7.4 and more recent is cmake only, this file has been removed starting from that release.
xgettext
- xgettext
- Extract translatable strings from given input files. See --language for supported list:
- --language=NAME
- recognise the specified language (C, C++, ObjectiveC, PO, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Smalltalk, Java, JavaProperties, C#, awk, YCP, Tcl, Perl, PHP, GCC-source, NXStringTable, RST, Glade, Lua, JavaScript, Vala, Desktop)
- Options, which we should check:
- --copyright-holder=STRING
- set copyright holder in output
- --foreign-user
- omit FSF copyright in output for foreign user
- --msgid-bugs-address=EMAIL@ADDRESS
- set report address for msgid bugs
- ↑ Before version 5.0 stable was named maint and future master. Discussionand Announcement
- ↑ https://www.gnu.org/software/guile/manual/html_node/Formatted-Output.html
- ↑ https://www.gnu.org/software/guile/manual/html_node/Scheme-Write.html
- ↑ Bug 797725 - Untranslatable string "For Period Covering ~a to ~a"
- ↑ Without LANG=C you would see localized standard buttons, but for now you want to see everything in US English.
