I have 2 types of users of my API: ones who want translated error messages and ones who don't. I've tried 2 ways so far:

  1. return both translated and untranslated message (https://github.com/Mudlet/Mudlet/pull/936/commits/0479c3f3dcd3446da38d7e4c6bf19636f8adfa6f). I don't like this because it is least efficient both in terms of space and memory.
  2. Allow the caller to translate it themselves. That's messy as heck though (https://github.com/Mudlet/Mudlet/pull/936/commits/215970a1ac1ca45106fef11701b79bc83031004d).

What are the best practices about doing this?

  • If your users specify the translated language they want with a standard language code, then you could use a special/reserved code (e.g. 'qaa' or 'und') to request the untranslated version. – Bart van Ingen Schenau Apr 21 '17 at 9:04

What are the error messages about? If you're talking about exceptions—that is, errors which look such as “Object reference not set to an instance of an object”, those errors are expected to be read by developers only, and never be shown to the end users. This means that translating them makes no sense.

As a provider of an API, you usually don't have to bother about translations, would it be error messages or anything else. You provide data, and it belongs to the application which uses this data to show it through a visual interface which, often, would have to be internationalized and localized.

A few examples:

  • If your API has a date to send to a client, it would be formatted in a non-ambiguous, neutral culture format such as 2016-12-24T14:37:06.58247Z. Then, the application may show it in a format which is actually suited for the user, including, for instance, the day of the week, or the month in full text and translated into the language of user's choice.

  • If your API has a floating point number, it would be serialized to JSON as 1725.38, and then the app will show it, for instance, as “1.725,38” for a French user.

In very rare cases, you do have to care about translations. Sometimes, you don't translate the data, but send the translations separately (for instance as a JSON file which associated keys to values for a culture specified in the HTTP request). Or you translate the actual data. Or you send the raw and translated data side by side.

If your API belongs to those rare cases, the choice of presenting the data should be guided by the requirements and constraints defined by your product owner, or, ultimately, by the customers. If they disagree, it's up to the product owner to decide if you follow the ones or the others, or develop two APIs.

  • 1
    The exception to this might be where the data is large portions of text. wikipedia articles for example. where you would request a language specific response – Ewan Apr 21 '17 at 3:43
  • Thank you! Will take this advice on board for the web-based interfaces. – Vadim Peretokin Apr 21 '17 at 7:57

Option 3:

  • provide a feature in your API which makes it easy for the caller to translate an untranslated error message, if they like to.

This could either be a translation function in your API which is called afterwards (with the untranslated error message or an error code as input), or a certain mode or state of your API (specific to the caller). It depends on the details of your API which of the two approaches is going to make more sense.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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