Added texdomain and portuguese files update

[pedro-mendonca]

No description provided.

[johnclause]

This one was intentional. It is translated by WordPress, since it is a string from the main installation. It goes to .pot file anyway, it does not hurt to have it there translated, but if there is no .po file for a language, it will be translated anyway from WordPress, if domain is not specified. In this case, it is important to keep translation the same as in WP, since otherwise a person may not recognize, which option is meant.

I know, we discussed a few similar cases, and I am not sure every time. It seems to me that it is better to have at least a few strings translated in the absence of .po, than nothing. It does not really make a difference to translator, since it gets to .pot file in any case. What do you think?

[pedro-mendonca]

I saw that this was already on the main WordPress .po because it's a link that appeared translated within a sentence not translated. So, I've found it's origin and translated it like it is in the main .po.
Yes, I think that the .po must be 100%, of course if you use a lot of strings similar to main WordPress localization files qTranslate will appear at leas somehow translated, but in the end that is not what's intended.

In the end I think it's not worthy to you to try to use strings already translated in the main WordPress, to brain expensive :)
With or without textdomain, if a specific localization don't exist, qTranslate will get it from the main files, so there is no difference, please always include it.

Translators should of course make their work perfectly according to WordPress terms, rules and guidelines.
This reminds me of the Translation Guide that we've not completed yet :)

[pedro-mendonca]

As I said above, I've spotted that already existing translation because I was lucky.
I suggest that if you want to use a specific title of something already existing, like this Admin Color Scheme, maybe you can add a comment to it, strings like Plugin titles, trademarks or author names can sometimes be confused with strings to translate. In this particular case a comment to explain it's context is the best way to inform translators what to do with that particular string.

[johnclause]

So, I've found it's origin and translated

I would not expect all translators to be that creative 👍 This really needs to be on the guide.

if a specific localization don't exist, qTranslate will get it from the main files

Are you sure about this? I think I tried something like this once and it was not translated, if domain specified, and it was translated, when domain is not specified, but now I am not sure.

[pedro-mendonca]

I would not expect all translators to be that creative 👍 This really needs to be on the guide.

That is already on the first part I've written in the Guide https://github.com/qTranslate-Team/qtranslate-x/wiki/Tips-for-Good-Translations#table-of-contents

Are you sure about this?

I've just checked this.
If the textdomain 'qtranslate' is there and the language file qTranslate-xx.mo exists, the string won't be searched in the main WordPress file even if the string exists there, the string will be obtained either from qTranslate-xx.mo (if the string exists there) or the main english php coded string in __('string' ...).
The only way that the string will be obtained from the main WordPress language files is not including the textdomain. But as naturally the string will be present in the .po file it should be translated, no one will look inside the code and shall have the goal of 100% translation.
It would take a lot of manual work and filtering to keep those kind of strings out of .po files, I sure think that is not the right way to go.

[johnclause]

So, if it is present in the .po file, and text domain is not specified, then translation stays unused, but does not hurt anything. We waste a bit of translator's time this way, but nothing gets broken, and one can potentially have benefit of seeing this string translated without .po file. This is especially beneficial in this case, since user knows how this option looks in WP, and there are no surprises. Otherwise, a user may not understand which option is meant.

Translators may never find out that such a string will never be used, and their time is wasted. But in the alternative way, they still need to translate it (same time is spent), then they need to make an effort to be sure that they translated it the same way as in WP (much more time needed).

From this, it seems to me that wasting a little bit of translator's time is the least evil, which outweighed by the benefits mentioned and by not asking the translator to find a matching string in WP. Besides, what if WP changes it? Unlikely, but possible. Then translator would need to do the search again. How translator would know when he needs to search again? It is getting more and more complex this way.

It seems to me that letting translator to wastefully translate such a string is not that big of a deal, since this is rather rare and unusual case.

I could also potentially filter those few special strings in the script in order to erase them from .pot file on each update.

What do you think?

[pedro-mendonca]

Well I'm a bit skeptic because of it's reduncancy, but as you've mentioned the translator is doing a redundant work.
I agree with you that the least effort solution is really obtain the translation from the main WordPress core.
In these cases, as it's a WP core option title, maybe makes more sense to realy filter it out from .pot. Still it means a bit more manual work for you.

To end this, I think that it won't harm to comment the string in the code, just in case some one catch it in Poedit in any case or if someone will try to add the textdomain again in the future.

To comments get parsed, it should be used the TRANSLATORS: start and the comment must be on the line above the string, the syntax is like this below:

qtx_configuration.php

/* TRANSLATORS: String obtained from WordPress core */
__('Admin Color Scheme', 'qtranslate' ) 

Comments catched in Poedit contain important contextual info on the string, like this:

qtranslate.pot

#. TRANSLATORS: Obtained from WordPress core
#: admin/qtx_configuration.php:1367
msgid "Admin Color Scheme"
msgstr ""

Whatever you choose, this kind of exceptional string deserve a comment like this to avoid further questioning.
If someone don't understand why it's lackint textdomain, it's explained in code comment.
If you include the textdomain, the comment explains what is it and whatever guidelines are suposed to follow.

[johnclause]

I added this comment and filtered this string in .pot in the script. I guess that is the optimum?
It will be 3.2.9.4, I cannot commit now because of other unfinished changes.

[pedro-mendonca]

As you've readded this string, it would be nice to flag that string also in .pot/.po files as I described above a not only in source php file.
Once you've added the comment to TRANSLATORS: it can be automattically commented in the generated .pot/.po files. That is the major benefit of having it commented, not only in the source php file.

[johnclause]

'TRANSLATORS:' comment is apparently a feature of poedit only, xgettext ignores it. I did not quite get why it would be good to have them commented in pot/po files? How does poedit show commented strings? pot and po currently do not have such strings at all and translator would not need to worry about it. If one spots it in a source file, then comment helps to understand to ignore it. Why do we still want to put it in pot file commented? Would not it create a potential confusion?

[pedro-mendonca]

Comments is a native feature in Poedit and it puts a sign on each particular commented string so that the translator can read it easily. Poedit uses this because it's a native feature of .pot files (gettext)
https://codex.wordpress.org/I18n_for_WordPress_Developers#Descriptions

I think weather the .pot generator includes comments or not while parsing the source code is just a matter of settings.

[pedro-mendonca]

While I don't know how to operate with gettext scripting, I believe this is what it looks like:
http://en.wikipedia.org/wiki/Gettext#Programming

This might be the option you need.
xgettext --add-comments=/

[pedro-mendonca]

I've read somewhere that the TRANSLATORS: was some kind of default setting, but it's probably customizable to anything you would prefer.
Example:
http://stackoverflow.com/questions/16504606/inserting-translator-notes-comments-in-php-files/16505465#16505465

[pedro-mendonca]

Commented strings is a lot used, specifically in these cases of contextual help, where de developer gives some guidelines of the path to folow or the context.

The strings get marked as commented and when clicked a comment window is shown with the text parsed from the source code comment.

If you want I can make a screenshot of Poedit to explain this a bit better and eventually show you other softwares that make use of this usefull feature.

[johnclause]

Wow, thank you 👍 I was using 'man xgettext', searched for word 'TRANSLATORS' and got nothing.

I will enable '--add-comments' it in the call to xgettext.

But anyway, why do we need to put in pot file a string that does not need to be translated? I can easily enough put in pot and then comment it out with an additional action, and then it will not get propagated to .po anyway, is that right? I currently do not have a cycle to modify all .po files, they go native defined by pot.

[pedro-mendonca]

The string will be caught by any parser, xgettext or Poedit, and someone in the future might find it.
For this, it should be commented as unnecessary in the source code, just to avoid further questioning on it's textdomain, as I did :)

If .pot/.po is generated by gettext you can control it to not include that particular string.
If you or someone else in the future would parse ir without that manual exclusion, the string is already documented. The comment will appear and the translator will no that it is not necessary to translate.

[pedro-mendonca]

You can now choose to exclude ir or not, but It's better to consider that if the workflow changes, you wouldn't have to think on this subject anymore as you've already prepared the .pot for the case of .po don't have any exclusions.

I think this is already long enough and you've already understood the purpose of comments for future needs. I've been explained this for this string just for dev/translators workflow optimization.
For this specific string it's your call and there is no need to make you spend more time on this

[johnclause]

If .pot/.po is generated by gettext you can control it to not include that particular string

I remove it with an additional scripted editing from pot file. If you find an option in xgettext to ignore a specific, let me know.

If somebody parses the sources on their own and find this string, then 'TRANSLATORS:' comment in the source will tell them why it is not included in pot file at first place. Why this is not good enough?

Actually, I can use my own custom alias instead of '_e' in that place and no parser will find it. Is that better?

[pedro-mendonca]

If somebody parses the sources on their own and find this string, then 'TRANSLATORS:' comment in the source will tell them why it is not included in pot file at first place. Why this is not good enough?

Just because without comment on the .pot there won't be any mark on that specific string and I'm pretty sure that a translator only check source code in case of having a doubt, and if he knows how to do it.
Inlcuding the existing comment on .pot transports it to Poedit GUI and it's way more friendly, and for this work, most of it is already done.

Having the comment on the source code and not having it parsed to .pot is like making a delecious cake and forget to eat it :)

[pedro-mendonca]

Actually, I can use my own custom alias instead of '_e' in that place and no parser will find it. Is that better?

Yes, you can use another custom alias, but to garantee that no one will ever find it you will need to hide it in a custom not listed in gettext keyword. Is that possible? Won't it generate a php error? I'm not saying it will, I really don't have a clue without testing.

I think that creating a well protected exception like is taking a lot of energy maybe because it's not to natural to the usual worklow. I'm sorry of beeing the devil's advocate I really don't want you to put unnecessary effort on this. I'm just trying to help by looking at all possibilities and their consequences.

[johnclause]

taking a lot of energy

No, it is very simple, and the more I think about it, the more I like it. This is perfect, and I can use it for all other strings that are already translated in WordPress. This is the best solution, that I have seen so far for this problem. I really appreciate your discussion, which resulted in this 👍. I already added function 'qtranxf_translate_wp' for that purpose, and I can now cancel my custom piece in the script. All became as simple as possible. 👍 👍

[pedro-mendonca]

This is particularly good to translate native WordPress labels like menus, options etc. 👍
Very simple indeed, well done :)