GNOME Bugzilla – Bug 670106
gtkmm-documentation: Mark code snippets as not for translation
Last modified: 2018-05-22 12:12:52 UTC
The gtkmm package includes the examples shown in the documentation. However, such examples are only in English. This is no minor issue since the code is really hard to understand when all the identifiers are in a language you don't understand. These examples are also included in the documentation itself. Although they could be translated there, they would be different to those included in the package. It would be a good idea to make a po file linked to the example code.
At least in my part of the world (Europe) I have a strong distaste for non-English identifiers in source code, because English is the common language of programmers. After all, the gtkmm API itself is in English, so you can't really use gtkmm, or any other popular API, if you don't understand English. However, I can hardly force you to work in a particular way. I might consider a patch that does this, but I'm unlikely to work on it myself. It would need to ensure that the translated source code builds during "make check", just as the current source code does. That's why it's in separate source files, instead of inline.
[Setting QA Contact of all open gtkmm/documentation tickets to 'gtkmm-forge@' so people interested in following reports' changes via the users watchlist can still follow if the assignee is changed to a real person.]
Murray, I agree with you since the API itself is in English and translating the example code would also mean spending a lot of valuable time. We'll leave the code untouched in the documentation. Thanks for your time.
Just a question... if there are no plans to get examples translated in the tutorial, could you please mark them as non-translatable strings? This could avoid confusing translators, since, for example, french translators have translated the comments in the code, but if this code should be left in the tutorial exactly as it is in the source file, these comments should not be translated, should be? Thanks
> for example, french translators have translated the comments in the code The comment text from the main examples does not appear in the XML file that is processed to create the .pot and .po files. I guess you mean the comments in the snippets of code that are written directly into the DocBook instead of being imported from .h/.cc files. For instance: http://git.gnome.org/browse/gtkmm-documentation/tree/docs/tutorial/fr/fr.po#n5404 I see no great harm in translating those few comments, as they appear in between explanatory paragraphs that are translated. However, I do have some fear about translating these code snippets, so I'd welcome a patch that: a) Somehow prevented their translation. b) Moved those comments into the main text.
Yes, I mean those ones. We have decided not to translate them, since we want these snippets appear in the manual exactly as they appear in the source files. About the patch, I can investigate how to markup strings as untranslatable. I'll comment you any progress I do on it. Thanks again! P.S. Since this bug has another task opened, I'm reopening it until we be able to generate and apply the patch
How do you translators generate and update the .po files? I can see from comments in the .po files that they have been generated from the C/gtkmm-tutorial-in.xml file (which is now called C/index-in.docbook), probably with xml2po. But the Makefile in gtkmm-documentation/docs/tutorial can only generate .po files from C/index.docbook, which contains all the example code. Have translators got their own set of scripts and Makefiles for updating .po files? (I mean that part of the updating which is done with xml2po or itstool + msgmerge.) gtkmm-documentation now uses yelp-tools instead of gnome-doc-utils: https://git.gnome.org/browse/gtkmm-documentation/commit/?id=25dc95f31542548ff16290ee5dc3d14db2e66395 And yelp-tools use itstool to generate .po files. itstool is very flexible. It would probably be possible to tell it that <programlisting> elements in the xml file shall not be translated, and thus not included in the .po files. I made a quick test with an <its:rules> element, as described at http://www.w3.org/TR/its/#trans-datacat. <programlisting> elements were excluded from the .po files, but it had unacceptable side effects for <programlisting> elements that were embedded in a <para> element. I still think it would be possible to get it to work acceptably, but I don't want to make more tests until I know that it would be useful for translators. Do you want all text within <programlisting></programlisting> excluded from the .po files? If you want it, do you think all groups of translators want it, including the French translators, who do translate comments in code snippets?
I found the following note at https://l10n.gnome.org/module/gtkmm-documentation/ HELP_ID doesn't point to a real file, probably a macro. Can't generate POT file, using old one. The pot-file at https://l10n.gnome.org/POT/gtkmm-documentation.master/docs/tutorial.master.pot looks quite old, and has been generated from C/gtkmm-tutorial-in.xml, which was renamed to C/index-in.docbook when we switched from gnome-doc-utils to yelp-tools on 2014-04-04. https://git.gnome.org/browse/gtkmm-documentation/tree/docs/tutorial/Makefile.am HELP_ID = gtkmm-tutorial Is our Makefile.am incompatible with some translator tool? https://wiki.gnome.org/Apps/Yelp/Tools/yelp.m4 says HELP_ID The ID of the help document. This determines the install location, and will be referenced in the help: URIs used in your application. It's the name of the install directory. It's not necessarily the name of an input file to xml2po or itstool. At least, that's how the description has been interpreted.
I have filed damned-lies bug 749860.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtkmm/issues/7.