What are the best practices for JSON response from multi lingual API

Question

I wanted to add languages to the current API response in English. The current API response looks like this:

{
   status : "success",
   data : {
    query: "contains search query",
    queryType: "search"

    results: [
        {
            title: "Marvel Captain America T-shirt",
            price: 624,
            category: "t-shirt",
            gender: "men",                  
        },
        .....
    ],
    language: "english",
    currency: "rupee",    
   }
}

There are two ways I can go about developing the API, one would be to use different cores for API response, and call according to language preference in the app but my app also requires certain English elements to be preserved. The other way being to put all the languages in the response with a certain structure to differentiate each one. In either case I want the english elements to be preserved.

So if gender: 'men', but language is french, so I want an additional field like gender_display: 'hommes' or gender_fr: 'hommes'

Addition: The search results are coming from Solr

Answer 1

When it comes to: [Internationalization | globalization | localization ] one of the most popular standards is i18n. From coding perspective is all about creating a "resource dictionary".

Different libraries have implemented this standard and their principles covers from translations to conversions when it comes to things like currencies, dates and numbers.

For instance i18n-js suggests this structure:

I18n.translations = {
            en: {
                hello: "Hello World!"               
            },
            "pt-BR": {
                hello: "Olá Mundo!"
            },
            "de": {
                hello: "Hallo Welt!"
            },
            "nb": {
                hello: "Hei Verden!"
            }
        };

   I18n.t("hello", {locale: "en"});    //returns  "Hello World!"
   I18n.t("hello", {locale: "pt-BR"}); //returns "Olá Mundo!"

There is a JQuery plug-in that may help as well:

$.i18n.load({ a_key: 'translated string %2$s - %1$s' });
$.i18n._('a_key', ['order', 'in'])); //returns 'translated string in - order'

Conclusion

To define the structure of your JSON it is recommendable to select first the Framework that suits better your needs and follow the best practices from the community. This will make the process of decisions more guided and backed up in the experience of a community.

Answer 2

One question you might ask yourself:

How many languages, and will different editors be working on the API files for each language, each specializing in one language? If you will have different editor per language, it might suit you to have one [set] of API files per language. However, instead of repeating everything for every language, (perhaps the price remains the same for all for example,) you can have a master API set in one language and just store only what is different to the master in the other localized API sets.

Say you're coding in (by way of example of an implementation) JavaScript and jQuery, you could then use jQuery's extend function to easily overlay your localized API on top of the master API. An advantage of this is that if your localization file is missing a translation, you'd fall back on the master API's wording.

Caveat: This may not necessarily be the best approach for your situation, since you've only provided general information. Hopefully though this suggestion is either useful or food for further thought. I've also made the assumption you're dealing with API files, since this is often the case with localization, but you may have DB-driven content or something else.