Plugin queries remote API and under certain circumstances (mostly errors) displays textual messages from API responses. All messages in API responses are in English, but since they are more or less integrated in plugin it would make sense to make them localized and display-able in different language to match plugin's interface.

Theoretical question - should such messages be localized at all or are they out of scope for localization?

Coding question - how do you even localize such and retain compatibility with related tools? Does something like __( $message ); even make sense?

In the past I used Codestyling Localization which relies on scanning plugin's source to extract strings... But there is nothing to extract since strings are not contained in plugin's body.


2 Answers 2


Should such messages be localized at all or are they out of scope for localization?

Yes, they should be localized ... but don't depend on the text returned by the API.

Does something like __( $message ); even make sense?

Not really. First of all, you're not providing a text domain for the string to use in localization. It should really be __( $message, 'my-text-domain' );. Even then, if you don't have a static list of values for $message, localaization is a moot point.

What You Can Do Instead

The Robustness Principle is a great thing to keep in mind whenever you integrate content from an external API. You can never fully trust what the API gives you ... the original owners might change things around without notifying you, or their system might break and provide erroneous information. So you should always:

Be conservative in what you send; be liberal in what you accept.

If you already know what content the API will return (i.e. a static list of strings), put that in your plug-in. Then use a sanitation method to map what the API returned to your localized strings.

For example:

$map = array( 
    'This is one return' => __( 'This is one return', 'my-text-domain' ),
    'This is another' => __( 'This is another', 'my-text-domain' )

sanitize_api_feedback( $api_sent ) {
    return $map[$api_sent];

In this way, you never actually use the raw output of the external API but always run it through your own filter. You have complete control over the text strings used and can run them through the standard localization filters as well.

If the API Return is Free-form

If you don't have a list of static strings returned by the API, this won't work. Then again, if the API returns free-form content you should either:

  1. Leave localization up to the API itself (if possible)
  2. Provide you end user with some other translation service ... maybe Google Translate

There's no way your plug-in can be responsible for translating free-form strings on the fly. But a static list of easily-expected error messages? That's definitely something you can, and should, do.

  • Yep, I had already requested to be provided with list of API responses, don't yet know if I will get one. Meanwhile decided to ask more general question, because I was interested in opinions if this is scope of localization at all.
    – Rarst
    Feb 28, 2011 at 17:31
  • @EAMann - i was about to finish typing my answer which is almost exactly like yours +1 @Rarst - just how do you dicide what goes in the localization scope?
    – Bainternet
    Feb 28, 2011 at 17:32
  • @Bainternet well, in the past I assumed scope to be messages contained in plugin's body. But this case kinda expands possible scope - API responses are not contained in plugin's body, but are tightly tied to plugin's functionality and are displayed by plugin for informational purposes.
    – Rarst
    Feb 28, 2011 at 17:39
  • 1
    @wyrfel I want to note that there will be at least one substantial benefit - messages clearly present in plugin's body are easier to scan with helper tools and generate translation files from.
    – Rarst
    Feb 28, 2011 at 17:58
  • 1
    When you translate errors from a lower layer (and I understand this is useful to provide a smooth experience), please also provide a way to display the original, untranslated error message. If the API messages are updated your translation could become outdated and even misleading. You are also more likely to find support when you have the original message, because then non-users of your plugin can understand what is going on.
    – Jan Fabry
    Mar 1, 2011 at 8:41

I think use __( $message ) is totally fine. I also think one would expect the API messages to be relatively constant. I'd say the best way to do it would be to use a domain that signifies the API itself rather than your plugin, so that the translations can be reused by whoever else accesses the same API: __( $message, 'wonder-api' ).

However, i'd first research if the API does support localization in itself. If so, the API's localization protocol should be used.

Ideally, though, you'd try to get a 'response code' from the API rather than a response message, so that you can map your own messages against the response codes. Most API's do deliver response codes alongside the messages.

  • __( $message ) should not be used. Whenever there is variable input, use sprintf() to localize the string. Sending variable strings to gettext defeats the purpose of localization. If it's too variable to localize every possibility, it's too variable for localization to be of any use. Feb 28, 2011 at 17:31
  • I think that __( $message ) (yeah, plus domain omitting that for discussion) will technically work, but I am not sure if it is supposed to be used like that. I cannot find instances of such usage in core (do see some in third party plugins). Edit Submitted and saw @John P Bloch comment, seems my doubts are not unfounded.
    – Rarst
    Feb 28, 2011 at 17:33
  • @John P Bloch: While you are right from a general, out of context, point of view, the context here is responses from an API that can be expected to have limited variability. There simply isn't a point in doing something like if ($api_message == 'api message') $message = __('api message') or i don't know what you'd imagine?
    – wyrfel
    Feb 28, 2011 at 17:41
  • On response code - also crossed my mind, but in this specific case it's a mess. Without getting into boring details it is two layers of API and error codes can be in different fields or just null. Completely unreliable.
    – Rarst
    Feb 28, 2011 at 18:06
  • @wyrfel Even if it was a good idea to use __( $message ) (I agree with John - that it should not be done), you are really alienating the most important person: The Translator. How are they going to know what to translate unless it is explicitly stated?
    – mfields
    Feb 28, 2011 at 18:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.