Author Topic: Making use of developers notes to translators? (Read 1529 times)

aputsiaq · April 20, 2015, 04:46:25 am

Hi,

I'm raising an issue not with a particular string, but about the general approach to the translation process from the beginning to the end.
I sometimes run into difficulties understanding a particular string, e.g. "Office Credit Card contribution" in CRM/Contribute/Form/Contribution.php (line 1590).
I'm not sure how to understand Office Credit Card contribution - does it have something to do with "taking an office" or is it a contribution made by a corporate credit card (from a specific office)?

In Transifex I get the following fields and information for this particular string:
Key: Office Credit Card contribution
Size: 4 words
Occurrences: CRM/Contribute/Form/Contribution.php:
Context: None
Resource: contribute

Other times the English strings are abbreviated (e.g. "n/a"), and it would be nice to know whether we as translators should try to limit the length of the string in our native language as well.
It would be nice if the Context field had said something like: "Contributions made by corporate office credit cards, string should be kept below 40 characters." Obviously the context field is just an example, as I don't understand the string in question.

Transifex allows for developer notes to translators, that are written in the code, to get passed into the system. From what I understand this makes it possible to pass information to the context field.
Exactly how it would work from the PHP code to Transifex would be of interest to me, as it would allow me and others improve the code base with filing bugs or suggesting developer notes to other translators.
Ideally proof readers, usability folks and those documenting CiviCRM would get involved at this level as well, to improve the clarity and consistency of the strings + provide useful background for the translators.

Cheers,
Aputsiaĸ

mathieu · April 20, 2015, 06:25:19 am

Hi,

Welcome to the CiviCRM community forums, and thanks for raising those issues.

To respond to the general workflow:

* the "context" field isn't as useful as it sounds: it aims to provide a general idea of where the string is found, for example: menu, list header, label, etc. For some languages, this can be really important to decline the string properly. One infamous example of where this would be useful is to properly translate the string "Home" (which can mean 'start' or 'residence').

CiviCRM does not use contexts extensively. I have to admit it has not been my priority, since except 2-3 strings (Home), there are not many incidents reported by translators. It would really help to translate, in my opinion, only to provide a more specific translation in some cases. For example, knowing whether "Office Credit Card contribution" is a label, header or general string, would not help much.

* in Transifex, translators can add notes to individual strings, and this can help to avoid ping-pong between translators who interpret strings differently and decide to "fix" it (from their point of view). Unfortunately, I don't think we see notes from other languages, which could be useful to reduce duplication of efforts.

* Length of strings: Generally I would recommend to try and use a string of equivalent length (ex: "n/a"). However, it's a good example, perhaps we shouldn't use "n/a" as much as we do. It might be obvious to tech people and bureaucrats, but to mere mortals, volunteers, etc, it's yet-another-annoying-acronym. However, the best way to fix that, is to fix it in the code, not in the translation.

Which brings us back to the original issue: "Office Credit Card contribution" is most probably a bad strings even for English: looking at the code says nothing about the string, but the commit (code change log # e0a8df2b) has this comment:

CRM 15488 Include invoice description in back office Credit Card Transactions
https://issues.civicrm.org/jira/browse/CRM-15488

So I think the string really should be "Back Office Credit Card contribution" (same for the string regarding back office memberships).

I would treat those types of errors as normal CiviCRM bugs (requiring us to create an issue, patch the code, push a new string to Transifex eventually). For non-programmer translators, posting on this forum is good enough, usually one of us will catch it and create the issue, patch, etc.

Sorry for the long answer, and probably not very satisfactory, but in short, I would recommend posting any questions here. Translators give a good critical review of the quality of the strings in CiviCRM which are often easy to ignore in English, but I think it reflects on the quality of the software in one way or another.

aputsiaq · April 21, 2015, 07:08:16 am

Thanks for the reply.
It provides the needed information in order to move forward.
I'll try to clarify and expand on my concerns, and also point to a similar discussion in the Drupal community.

My main departure is that I have a different understanding of the context field. If I'm wrong about the context field as such, the following concerns still ought to be valid though.

I have personally benefited from "developer-to-translator notes" in other projects, although I'm not too much into the technical about how these notes got transferred from the code to Transifex (in gettext I believe this is done through msgctxt). There are many language teams who translates and CiviCRM is getting more complex to translate - therefore the risk of buggy strings increases.
My take is that the context field has a wider range of use cases:

reduce linguistic ambiguities (e.g. many words can be read as a noun or verb: file, search, empty, ...)
convey useful remarks ("keep below 10 characters", "Trxn Date is short for something-unknown-to-me Date", etc.)
a way of documenting and explaining highly technical strings (the hardcore technical or say financial modules contains some difficult strings)

I came across a Drupal discussion from 2008 where the usefulness of gettext msgctxt is discussed:
https://www.drupal.org/node/334283
As one person suggests (#19 KarenS), there are several different use cases for contexts.

mathieu · April 21, 2015, 08:56:28 am

Good point, and interesting discussions on the Drupal side.

I only read in diagonal for now, did you see any documents/guidelines that could provide inspiration? I will try to do some tests/brainstorm in the next week (code sprint) and see what sort of guidelines we could suggest.

My top priority however, is making sure we can have code style tests to make sure that developers use ts() correctly. Having some way of seeing new strings quickly could also be good, to catch sentences such as those before the final release (I do some review, but with very limited time, and mostly manually).

aputsiaq · April 21, 2015, 11:16:51 am

I don't know how Drupal implemented it, but this article makes it clear that it was introduced in version 7:
https://localize.drupal.org/node/2109

A comment points to this documentation node:
https://www.drupal.org/node/1369936

It looks like the Drupal code gets quite ugly with the introduction of contexts:
- '#title' => t('Scale'),
+ '#title' => t('Scale', array(), array('context' => 'Number of digits')),

Cheers, Aputsiaĸ

mathieu · April 28, 2015, 05:02:25 pm

At the code sprint someone asked me how a string such as "LTS" (for Long Term Support) should be tagged in ts().

I looked at the Drupal docs, as well as the gettext manual:
https://www.gnu.org/software/gettext/manual/html_node/Contexts.html

Basically, both advise to choose contexts wisely, because changing them is really annoying to translators (effectively requiring to re-translate). They can't be used to send a comment to translators (which would have been very cool).

I think some contexts are more obvious than others. For example, "address" would be an obvious candidate (for the string "Home"). Another potential one could be "payment", but I don't have a specific example at hand (could "Total" be ambiguous in some langages?). In other cases, I would recommend fixing the string to be clearer. i.e. contexts are really useful for 1 word strings, but otherwise the string should be clear enough.

I did a bit of grepping through the strings, and found ~ 1160 strings of one word:

Code: [Select]

$ grep msgid *.pot  | grep -v provinces.pot | grep -v countries.pot | grep -v menu.pot | grep -E '"\w+"' | wc -l
989

Out of those 989, 140 are language names, so ~ 849 strings.

(I ignored provinces, countries and menu, since they already have a context)

The output is kind of scary.. we can see a lot of obvious errors:

event.pot:msgid "6"
event.pot:msgid "7"
event.pot:msgid "8"
event.pot:msgid "9"
event.pot:msgid "10"

There are also classics like these ones:

common-components.pot:msgid "Frequency"
common-components.pot:msgid "before"
common-components.pot:msgid "after"
common-components.pot:msgid "Repeat"
common-components.pot:msgid "every"
common-components.pot:msgid "until"

More details here:
http://paste.debian.net/169765/

Might be a good starting point to use that list for contexts?

aputsiaq · May 02, 2015, 09:01:21 am

Hi,

[Not] requiring unnecessary re-translation is important. In Transifex there is a pretty good translation memory, but still it ought to be avoided. That is: unless the existing string are really ambiguous and important to get exactly right - and there are some of those for sure.

My main concern isn't strings with one word per se. There are a list of strings with words that can be both nouns and verbs, but also say adverbs (build, close, design, empty, file, import, record, search, ...).
There are a variety of other instances, see for example section 10.4 in Oracle's guidelines: http://docs.oracle.com/cd/E24705_01/doc.91/e24223/translation_issues.htm#g8d6ab57f7cedeaac_ef90c_10a77c8e3f7__7882

While translating CiviCRM I've come across several strings, where I stumble a bit - and I might have translated these and others in a wrong way into Danish.

Here is a short selection:

templates/CRM/Event/Form/ManageEvent/ConfirmRepeatMode.tpl:
Update repeating %1

-- In Danish we in principle need to know whether %1 will be a term in singular or plural form.

templates/CRM/Event/Form/ManageEvent/ConfirmRepeatMode.tpl:
Only this %1

-- In Danish we would need to translate "this" with either "denne" or "dette", depending on which kind of noun %1 refers to; is it a participant or an event? Sometimes the translation of "this" should be omitted, as it would be implicit depending on the context. I pretty sure the German translators run into similar problems in a even higher degree, as the grammar concerning nouns are even more complex in German compared to Danish. E.g.: "Only this event" -> "Kun dette arrangement", but "Only this participant" -> "Kun denne deltager".

xml/templates/message_templates/contribution_recurring_edit_html.tpl:,
xml/templates/message_templates/contribution_recurring_edit_text.tpl:
Recurring contribution is for %1, every %2 %3(s)

CRM/Contact/BAO/Query.php:
Greeting %1 %2

-- These kinds of strings containing placeholders can be somewhat tricky as well. "Recurring contribution is for %1, every %2 %3(s)" is the most difficult and important of these to get exactly right, as it describes something related to money. But it is very hard to see exactly how to translate this without looking into the code. My basic approach has been to just keep this blob of "%2 %3(s)" the same in Danish. I assume that "Greeting %1 %2" stands for say "Greeting mr. Smith", and these cases are okay.

In other words, some strings containing one word only would benefit from a comment saying "noun" or "verb", while other complex sentences also could benefit.
A broader approach to understand translations issues is provided in the Oracle page: http://docs.oracle.com/cd/E24705_01/doc.91/e24223/translation_issues.htm#EOTDG00117
The main concern in this thread is just the use cases for comments.

Cheers!

mathieu · September 30, 2015, 05:36:35 pm

Hi Aputsiaq (and others following this thread).

Björn posted a blog post on this issue, and intends to work on this during the UK sprint. Please take a look, and contribute to the wiki page!
https://civicrm.org/blogs/bjoerne/lost-in-translation

wiki:
https://wiki.civicrm.org/confluence/display/CRMDOC/Collection+of+translation+conflicts

CiviCRM Community Forums (archive)

News:

Author Topic: Making use of developers notes to translators? (Read 1529 times)

aputsiaq

Making use of developers notes to translators?

mathieu

Re: Making use of developers notes to translators?

aputsiaq

Re: Making use of developers notes to translators?

mathieu

Re: Making use of developers notes to translators?

aputsiaq

Re: Making use of developers notes to translators?

mathieu

Re: Making use of developers notes to translators?

aputsiaq

Re: Making use of developers notes to translators?

mathieu

Re: Making use of developers notes to translators?