[RFC] Localized descriptions

[Naoto-Ida]

We are currently thinking about using GraphQL for our public API.

We are based in Japan, so we'd like to have localized descriptions for each GraphQL object for our local developers who are interested in trying our API.
Is there current support for this, or is it something that could come in the future?
Thanks.

[leebyron]

I think this is a great idea. Perhaps the description introspection field should include an argument selecting language, though I'm sure there are other options as well.

This needs a champion to write the spec text and propose implementations in at least the GraphQL.js reference implementation.

[ivome]

I added localization of descriptions to one of my GraphQL implementations by switching the locale context internally in the server depending on request headers and/or a locale that is appended to the API URL. This works with the current GraphQL spec but is very specific to this implementation. I think formalizing this is a great idea!

A few random thoughts:

I think this is a great idea. Perhaps the description introspection field should include an argument selecting language

What would that argument look like? Just a simple String? How does a client know what languages are supported by a GraphQL server? Should that be exposed via the introspection API? We could also add a new Locale Enum type with supported ISO language codes to the spec which could also be used elsewhere in the schema, but this type could potentially have several hundred values if you consider all country and language code combinations. Or a new Locale scalar type which could have validation for input values etc. The downside would be that those types might be unwanted artifacts in GraphQL Servers that don't support localization.

Schema Definition Language:
I like how we can add descriptions in the SDL right next to the type definition with the current spec. Should the localized descriptions live in the SDL documents?

[Naoto-Ida]

Even though I am not part of the company where this topic was of concern, I'm still quite interested in the development of this feature.

To avoid bloating the spec, I guess the most logical thing for now is to pass the locale somehow to the resolver method and use that to render the appropriate localized description.