load_textdomain: Incorrect PHPDoc and possibly unwanted merging behaviour

[rovo89]

The PHPDoc for load_textdomain in wp-includes/l10n.php says that loading a file for an already existing domain will fail. This was correct at the time when the comment was written, but the function has been changed after that and now merges the translations.

However, if a string has been translated in both the already loaded and the new file, the existing translation will be used. In my opinion, it should be the other way round. If I'm satisfied with the translations in general, but want to change just a few of the strings, I have to change the translation file (which would be necessary again for every new version). It would be easier to create a new file with only the changed translations. However, the default domain is loaded at the very beginning, so I can't simply use load_textdomain('default', $myfile);

The attached patch changes this behaviour so that new translations will overwrite existing ones. The PHPDoc should then be changed to reflect the actual behaviour in case of an existing domain. Maybe the @uses references are outdated as well, I'm not sure.

[rovo89]

New translations overwrite existing ones

[nbachiyski]

The current behavior is mostly inspired by bbPress integration. Although the use case of replacing translations with custom ones seems logical, I haven't seen anybody try to do that.

Updating the docs seems enough for now.

Attched is a patch, which updates the docs and adds proper return values for load_textdomain().

[rovo89]

I actually thought about replacing some translations depending on the theme. Well ok, as this call to load_textdomain() would happen in my code then (not in the core), I can work around this.

The patch looks good, just one thought: load_plugin_textdomain() etc. call load_textdomain(), maybe these should pass the return value on?

[nbachiyski]

Right. I updated the patch.

[ryan]

(In [11680]) Update load_textdomain() phpdoc. Props nbachiyski. fixes #10286 for trunk

[ryan]

(In [11681]) Update load_textdomain() phpdoc. Props nbachiyski. fixes #10286 for 2.8.1

[hakre]

related / follow up: #10527 - make merging optional

[hakre]

Regarding the merging Feature, see #7376 for implementation details.