Rename clearingLang to withoutLang

documentation/manual/releases/release27/migration27/JavaHttpContextMigration27.md

@@ -419,7 +419,7 @@ public class FooController extends Controller {
     }
 
     public Result action() {
-        return Results.ok("Hello").clearingLang(messagesApi);
+        return Results.ok("Hello").withoutLang(messagesApi);
     }
 }
 ```

documentation/manual/working/scalaGuide/main/i18n/ScalaI18N.md

@@ -87,13 +87,13 @@ The preferred language is extracted from the `Accept-Language` header (and optio
 The [`I18nSupport`](api/scala/play/api/i18n/I18nSupport.html) also adds two convenient methods to `Result`:
 
 * `result.withLang(lang: Lang)` is used to set the language using Play's language cookie. 
-* `result.clearingLang` is used to clear the language cookie.
+* `result.withoutLang` is used to clear the language cookie.
 
 For example:
 
 @[lang-cookies](code/scalaguide/i18n/ScalaI18nService.scala)
 
-The `withLang` method sets the cookie named `PLAY_LANG` for future requests, while clearingLang discards the cookie, and Play will choose the language based on the client's Accept-Language header.
+The `withLang` method sets the cookie named `PLAY_LANG` for future requests, while withoutLang discards the cookie, and Play will choose the language based on the client's Accept-Language header.
 
 The cookie name can be changed by changing the configuration parameter: `play.i18n.langCookieName`.
 
@@ -135,4 +135,4 @@ you should expect the following results:
 
 The default implementation of [`MessagesApi`](api/scala/play/api/i18n/MessagesApi.html) is [`DefaultMessagesApi`](api/scala/play/api/i18n/DefaultMessagesApi.html).  You can see [[unit testing|ScalaTestingWithSpecs2#Unit-Testing-Messages]] and [[functional testing|ScalaFunctionalTestingWithSpecs2#Testing-Messages-API]] examples in the testing section of the documentation.
 
-You can also use [`Helpers.stubMessagesApi()`](api/scala/play/api/test/Helpers$.html#stubMessagesApi\(messages:Map[String,Map[String,String]],langs:play.api.i18n.Langs,langCookieName:String,langCookieSecure:Boolean,langCookieHttpOnly:Boolean,langCookieSameSite:Option[play.api.mvc.Cookie.SameSite],httpConfiguration:play.api.http.HttpConfiguration\):play.api.i18n.MessagesApi) in testing to provide a premade empty [`MessagesApi`](api/scala/play/api/i18n/MessagesApi.html).
+You can also use [`Helpers.stubMessagesApi()`](api/scala/play/api/test/Helpers$.html#stubMessagesApi\(messages:Map[String,Map[String,String]],langs:play.api.i18n.Langs,langCookieName:String,langCookieSecure:Boolean,langCookieHttpOnly:Boolean,langCookieSameSite:Option[play.api.mvc.Cookie.SameSite],httpConfiguration:play.api.http.HttpConfiguration\):play.api.i18n.MessagesApi) in testing to provide a premade empty [`MessagesApi`](api/scala/play/api/i18n/MessagesApi.html).

documentation/manual/working/scalaGuide/main/i18n/code/scalaguide/i18n/ScalaI18nService.scala

@@ -81,7 +81,7 @@ class MyController @Inject()(val controllerComponents: ControllerComponents) ext
   }
 
   def homePageWithDefaultLang = Action {
-    Redirect("/user/home").clearingLang
+    Redirect("/user/home").withoutLang
   }
   // #lang-cookies
 
@@ -101,4 +101,4 @@ class MyClass @Inject()(val messagesApi: MessagesApi) extends LangImplicits {
     val messages: Messages = lang2Messages // implicit conversion
   }
 }
-// #using-lang-implicits-trait
+// #using-lang-implicits-trait

framework/src/play-integration-test/src/test/scala/play/it/http/JavaResultsHandlingSpec.scala

@@ -355,11 +355,11 @@ trait JavaResultsHandlingSpec extends PlaySpecification with WsTestClient with S
         response.headers("Set-Cookie") must contain((s: String) => s.equalsIgnoreCase("PLAY_LANG=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/"))
       }
 
-      "works with Result.clearingLang" in makeRequestWithApp() { app =>
+      "works with Result.withoutLang" in makeRequestWithApp() { app =>
         new MockController() {
           override def action: Result = {
             val javaMessagesApi = app.injector.instanceOf[MessagesApi]
-            Results.ok("Hello world").clearingLang(javaMessagesApi)
+            Results.ok("Hello world").withoutLang(javaMessagesApi)
           }
         }
       } { response =>

framework/src/play/src/main/java/play/mvc/Controller.java

@@ -96,7 +96,7 @@ public static boolean changeLang(Lang lang) {
     /**
      * Clear the lang for the current user.
      *
-     * @deprecated Deprecated as of 2.7.0. Use {@link MessagesApi#clearLang(Result)} or {@link Result#clearingLang(MessagesApi)}.
+     * @deprecated Deprecated as of 2.7.0. Use {@link MessagesApi#clearLang(Result)} or {@link Result#withoutLang(MessagesApi)}.
      */
     @Deprecated
     public static void clearLang() {

framework/src/play/src/main/java/play/mvc/Http.java

@@ -1027,7 +1027,7 @@ default boolean hasHeader(String headerName) {
         Optional<List<X509Certificate>> clientCertificateChain();
 
         /**
-         * Create a new versions of this object with the given transient language set.
+         * Create a new version of this object with the given transient language set.
          * The transient language will be taken into account when using {@link MessagesApi#preferred(RequestHeader)}} (It will take precedence over any other language).
          *
          * @param lang The language to use.
@@ -1038,7 +1038,7 @@ default RequestHeader withTransientLang(Lang lang) {
         }
 
         /**
-         * Create a new versions of this object with the given transient language set.
+         * Create a new version of this object with the given transient language set.
          * The transient language will be taken into account when using {@link MessagesApi#preferred(RequestHeader)}} (It will take precedence over any other language).
          *
          * @param code The language to use.
@@ -1049,7 +1049,7 @@ default RequestHeader withTransientLang(String code) {
         }
 
         /**
-         * Create a new versions of this object with the given transient language set.
+         * Create a new version of this object with the given transient language set.
          * The transient language will be taken into account when using {@link MessagesApi#preferred(RequestHeader)}} (It will take precedence over any other language).
          *
          * @param locale The language to use.
@@ -1060,7 +1060,7 @@ default RequestHeader withTransientLang(Locale locale) {
         }
 
         /**
-         * Create a new versions of this object with the given transient language removed.
+         * Create a new version of this object with the given transient language removed.
          *
          * @return The new version of this object with the transient language removed.
          */

framework/src/play/src/main/java/play/mvc/Result.java

@@ -262,7 +262,7 @@ public Result withNewFlash() {
     /**
      * Adds values to the flash.
      *
-     * @param values A map with values to add to this result’s flash
+     * @param values A map with values to add to this result's flash
      * @return A copy of this result with values added to its flash scope.
      */
     public Result flash(Map<String, String> values) {
@@ -276,8 +276,8 @@ public Result flash(Map<String, String> values) {
     /**
      * Adds the given key and value to the flash.
      *
-     * @param key The key to add to this result’s flash
-     * @param value The value to add to this result’s flash
+     * @param key The key to add to this result's flash
+     * @param value The value to add to this result's flash
      * @return A copy of this result with the key and value added to its flash scope.
      */
     public Result flash(String key, String value) {
@@ -310,7 +310,7 @@ public Session session() {
 
     /**
      * @param request Current request
-     * @return The session carried by this result. Reads the given request’s session if this result does not has a session.
+     * @return The session carried by this result. Reads the given request's session if this result does not has a session.
      */
     public Session session(Http.Request request) {
         if(session != null) {
@@ -352,7 +352,7 @@ public Result withNewSession() {
     /**
      * Adds values to the session.
      *
-     * @param values A map with values to add to this result’s session
+     * @param values A map with values to add to this result's session
      * @return A copy of this result with values added to its session scope.
      */
     public Result addingToSession(Http.Request request, Map<String, String> values) {
@@ -362,8 +362,8 @@ public Result addingToSession(Http.Request request, Map<String, String> values)
     /**
      * Adds the given key and value to the session.
      *
-     * @param key The key to add to this result’s session
-     * @param value The value to add to this result’s session
+     * @param key The key to add to this result's session
+     * @param value The value to add to this result's session
      * @return A copy of this result with the key and value added to its session scope.
      */
     public Result addingToSession(Http.Request request, String key, String value) {
@@ -527,7 +527,7 @@ public Result as(String contentType) {
     }
 
     /**
-     * Returns a new result with the given lang cookie. For example:
+     * Returns a new result with the given lang set in a cookie. For example:
      *
      * <pre>
      * {@code
@@ -555,7 +555,7 @@ public Result withLang(Lang lang, MessagesApi messagesApi) {
      * <pre>
      * {@code
      * public Result action() {
-     *     ok("Hello").clearingLang(messagesApi);
+     *     ok("Hello").withoutLang(messagesApi);
      * }
      * }
      * </pre>
@@ -567,7 +567,7 @@ public Result withLang(Lang lang, MessagesApi messagesApi) {
      *
      * @see MessagesApi#clearLang(Result)
      */
-    public Result clearingLang(MessagesApi messagesApi) {
+    public Result withoutLang(MessagesApi messagesApi) {
         return messagesApi.clearLang(this);
     }
 

framework/src/play/src/main/scala/play/api/i18n/I18nSupport.scala

@@ -109,14 +109,17 @@ trait I18NSupportLowPriorityImplicits {
      * For example:
      * {{{
      * implicit val messagesApi: MessagesApi = ...
-     * Ok(Messages("hello.world")).clearingLang
+     * Ok(Messages("hello.world")).withoutLang
      * }}}
      *
      * @return the new result
      */
-    def clearingLang(implicit messagesApi: MessagesApi): Result = {
+    def withoutLang(implicit messagesApi: MessagesApi): Result = {
       messagesApi.clearLang(result)
     }
+
+    @deprecated("Use withoutLang", "2.7.0")
+    def clearingLang(implicit messagesApi: MessagesApi): Result = withoutLang
   }
 }
 

framework/src/play/src/main/scala/play/api/mvc/Results.scala

@@ -420,7 +420,7 @@ trait LegacyI18nSupport {
      *
      * For example:
      * {{{
-     * Ok(Messages("hello.world")).clearingLang
+     * Ok(Messages("hello.world")).withoutLang
      * }}}
      *
      * @return the new result

framework/src/play/src/test/scala/play/api/mvc/ResultsSpec.scala

@@ -174,7 +174,7 @@ class ResultsSpec extends Specification {
         Some(Set(preferencesCookie, sessionCookie)))
     }
 
-    "support clearing a language cookie using clearingLang" in withApplication { app: Application =>
+    "support clearing a language cookie using withoutLang" in withApplication { app: Application =>
       implicit val messagesApi = app.injector.instanceOf[MessagesApi]
       val cookie = cookieHeaderEncoding.decodeSetCookieHeader(bake(Ok.clearingLang).header.headers("Set-Cookie")).head
       cookie.name must_== Play.langCookieName