+htp add selectPreferredLanguage directive incl. docs

akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala

@@ -58,6 +58,25 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
       responseAs[String] shouldEqual "request entity empty"
     }
   }
+  "selectPreferredLanguage-example" in {
+    val request = Get() ~> `Accept-Language`(
+      Language("en-US"),
+      Language("en") withQValue 0.7f,
+      LanguageRange.`*` withQValue 0.1f,
+      Language("de") withQValue 0.5f)
+
+    request ~> {
+      selectPreferredLanguage("en", "en-US") { lang ⇒
+        complete(lang.toString)
+      }
+    } ~> check { responseAs[String] shouldEqual "en-US" }
+
+    request ~> {
+      selectPreferredLanguage("de-DE", "hu") { lang ⇒
+        complete(lang.toString)
+      }
+    } ~> check { responseAs[String] shouldEqual "de-DE" }
+  }
   "validate-example" in {
     val route =
       extractUri { uri =>

akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst

@@ -197,6 +197,8 @@ Directive                                   Description
 :ref:`-responseEncodingAccepted-`           Rejects the request with an ``UnacceptedResponseEncodingRejection`` if the
                                             given response encoding is not accepted by the client
 :ref:`-scheme-`                             Rejects all requests whose URI scheme doesn't match the given one
+:ref:`-selectPreferredLanguage-`            Inspects the request's ``Accept-Language`` header and determines, which of
+                                            a given set of language alternatives is preferred by the client
 :ref:`-setCookie-`                          Adds a ``Set-Cookie`` response header with the given cookies
 :ref:`-textract-`                           Extracts a number of values using a ``RequestContext ⇒ Tuple`` function
 :ref:`-tprovide-`                           Injects a given tuple of values into a directive

akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/index.rst

@@ -10,4 +10,5 @@ MiscDirectives
    rejectEmptyResponse
    requestEntityEmpty
    requestEntityPresent
+   selectPreferredLanguage
    validate

akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/selectPreferredLanguage.rst

@@ -0,0 +1,25 @@
+.. _-selectPreferredLanguage-:
+
+selectPreferredLanguage
+=======================
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala
+   :snippet: selectPreferredLanguage
+
+Description
+-----------
+Inspects the request's ``Accept-Language`` header and determines,
+which of a given set of language alternatives is preferred by the client according to content negotiation rules
+defined by http://tools.ietf.org/html/rfc7231#section-5.3.5.
+
+If there are several best language alternatives that the client has equal preference for
+(even if this preference is zero!) the order of the arguments is used as a tie breaker (first one wins).
+
+Example
+-------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+  :snippet: selectPreferredLanguage-example