Working with Translations

Supported Languages

• Languages in the API are expressed as IETF language codes. (e.g. en for English or fr for French)
• A language is expressed in each REST request as the "language" parameter like this: /listings/12345?language=fr
• The supported languages are currently: (de, en, es, fr, it, ja, nl, pl, pt, ru). We are always adding to this list.
• "Machine languages" designate automated translations and have MACHINE_ prepended to their codes. (e.g. MACHINE_en for generated English text or MACHINE_fr for generated French text)
• If no parameter is given, English (en) is assumed.

Translation Quality and Bleedthrough

• For resources like a Category's name or a Country's name the content returned by the API will always be in the language you request, so long as that language is a supported language (de, en, es, fr, it, ja, nl, pl, pt, ru).
• For user-generated content like Shops or Listings, the content may not be available in all languages.
• The languages available for a piece of user-generated content (a Shop or a Listing) is controlled by which Translations the owner of that content has provided.
• If you request a language which is unavailable for a specific piece of user-generated content, content in the available languages will "bleed through" so that required fields (like a Listing's title field) will never be blank.

Bleedthrough Rules

Translations data for user-generated content must be in a language that is both supported by Etsy and available from the user who created that content. The following rules apply for reading any user-generated content's translatable fields:

1. Return the content in the language the user asked for.
2. If that content is not available, return machine language content based on the language the user asked for. For example, if the user requested french, return machine french content.
3. If that content is not available, return English content.
4. If English is also not available, return the content in the "Primary Language" of the seller account who created the content. (All shops have a Primary Language setting, and it doesn't have to be English.)

Bleedthrough Examples

For this example pretend a Listing has been translated by the Seller into English, French and German. Notice that requesting Chinese returns the same data as requesting English, since Chinese is not available or supported at all.

For this example pretend the Listing has been translated by the Seller into both English and German. Notice that requesting French or Chinese returns the same data as requesting English, since neither of those languages are available.

Translations as Resources

ShopTranslations and ListingTranslations are new types of resources in the API. This provides a more detailed perspective on the Translations data. These resources can be accessed individually like so:

The last parameter serves as the language parameter. The critical difference with the data returned by these resources is that they do not use the idea of bleedthrough. If you ask for data in a language the Seller has not provided, the result will be blank.

Translations as Associations

Translations records can be requested as part of another resource as an include parameter. This data may be helpful because it is not always clear where the translated data is coming from.

Examples

Request (English w/ Translations)

Here we request a listing in English and include its Translations as an association. If some translation languages do not exist they will not be included.

/listings/12345?language=en&includes=Translations

Response

{
    "title": Example Listing Title,
    "description": Example Listing Description,
    ...
    "Translations": [
        {
            language: en,
            title: Example Listing Title,
            description: Example Listing Description,
            tags: [ "en tag1", "en tag2" ]
        },
        {
            language: fr,
            title: Titre Annonce Exemple,
            description: Description de l'article Exemple,
            tags: [ "de tag1", "de tag2" ]
        }
    ]
}

Request (German w/ Translations)

Here we request a listing in German, but as you can tell from the included Translations this Seller has provided no data translated to German.

/listings/12345?language=de&includes=Translations

Response

{
    "title": Example Listing Title,
    "description": Example Listing Description,
    ...
    "Translations": [
        {
            language: en,
            title: Example Listing Title,
            description: Example Listing Description,
            tags: [ "en tag1", "en tag2" ]
        },
        {
            language: fr,
            title: Titre Annonce Exemple,
            description: Description de l'article Exemple,
            tags: [ "de tag1", "de tag2" ]
        }
    ]
}