Merge pull request #186 from pelias/request-language

docs for language codes

language-codes.md

@@ -0,0 +1,31 @@
+# Get search results in a particular language
+
+You can get search results in another language, if available, by specifying a target language code with your request.
+
+By default, search responses are in the default locale of the dataset. However, if you include a language code, the search attempts to return place names in the language you specified.
+
+If the language you requested is unavailable, then the default language is returned. In some cases, this is the local dialect, or it may be English for other datasets.
+
+## Request a specific language
+
+You can specify the target language code in the [BCP47 standard](http://www.rfc-editor.org/rfc/bcp/bcp47.txt) as either a query string URL parameter or an HTTP header.
+
+Note that a language code in the query string takes precedence over a code in the header. If you include an invalid language code, then you see a warning message and the search attempts to find a valid code, if one is available. Otherwise, the results fall back to default behavior.
+
+BCP47 language tags can contain three parts:
+
+   1. A language subtag (en, zh).
+   2. A script subtag (Hant, Latn).
+   3. A region subtag (US, CN).
+
+At this time, only the `language subtag` information is used to set the target language. The other options may be enabled in the future when additional data can be imported with text containing `script subtag` and `region subtag` variants.
+
+### Set language as a query string in the URL
+
+You can specify the language code using a URL parameter named `lang`.
+> eg. /v1/search?lang=de-ch
+
+### Set language in the HTTP header
+
+You can include the language code in the HTTP request header with the `Accept-Language` parameter.
+> eg. Accept-Language: de-ch