admin/spring-projects-spring-framework
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-framework synced 2026-06-08 17:33:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Modernize the DispatcherServlet Locale documentation

Browse Source 
The Java sample for "Locale Interceptor" shows a
`urlHandlerMapping.setUrlMap(Map.of("...` line due the inability to
disable the code chomping Asciidoctor extension with the code include
one. It will be fixed by a subsequent commit or a bug fix in
https://github.com/spring-io/asciidoctor-extensions.

Closes gh-36099
This commit is contained in:
Sébastien Deleuze
2026-01-06 11:03:46 +01:00
parent d752e80356
commit 3027d78f40
7 changed files with 218 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc
+4 -63
View File
@@ -54,44 +54,9 @@ information.
This locale resolver inspects a `Cookie` that might exist on the client to see if a
`Locale` or `TimeZone` is specified. If so, it uses the specified details. By using the
properties of this locale resolver, you can specify the name of the cookie as well as the
maximum age. The following example defines a `CookieLocaleResolver`:
[source,xml,indent=0,subs="verbatim,quotes"]
----
<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">
<property name="cookieName" value="clientlanguage"/>
<!-- in seconds. If set to -1, the cookie is not persisted (deleted when browser shuts down) -->
<property name="cookieMaxAge" value="100000"/>
</bean>
----
The following table describes the properties `CookieLocaleResolver`:
[[mvc-cookie-locale-resolver-props-tbl]]
.CookieLocaleResolver properties
[cols="1,1,4"]
|===
| Property | Default | Description
| `cookieName`
| class name + LOCALE
| The name of the cookie
| `cookieMaxAge`
| Servlet container default
| The maximum time a cookie persists on the client. If `-1` is specified, the
cookie will not be persisted. It is available only until the client shuts down
the browser.
| `cookiePath`
| /
| Limits the visibility of the cookie to a certain part of your site. When `cookiePath` is
specified, the cookie is visible only to that path and the paths below it.
|===
maximum age. The following example defines a `CookieLocaleResolver` bean:
include-code::./WebConfiguration[tag=snippet,indent=0]
[[mvc-localeresolver-session]]
== Session Resolver
@@ -115,31 +80,7 @@ You can enable changing of locales by adding the `LocaleChangeInterceptor` to on
accordingly, calling the `setLocale` method on the `LocaleResolver` in the dispatcher's
application context. The next example shows that calls to all `{asterisk}.view` resources
that contain a parameter named `siteLanguage` now changes the locale. So, for example,
a request for the URL, `https://www.sf.net/home.view?siteLanguage=nl`, changes the site
a request for the URL `https://domain.com/home.view?siteLanguage=nl` changes the site
language to Dutch. The following example shows how to intercept the locale:
[source,xml,indent=0,subs="verbatim"]
----
<bean id="localeChangeInterceptor"
class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
<property name="paramName" value="siteLanguage"/>
</bean>
<bean id="localeResolver"
class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/>
<bean id="urlMapping"
class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
<property name="interceptors">
<list>
<ref bean="localeChangeInterceptor"/>
</list>
</property>
<property name="mappings">
<value>/**/*.view=someController</value>
</property>
</bean>
----
include-code::./WebConfiguration[tag=snippet,indent=0]
framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.java
+38
View File
@@ -0,0 +1,38 @@
/*
* Copyright 2002-present the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolvercookie;
import java.time.Duration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
// tag::snippet[]
@Configuration
public class WebConfiguration {
@Bean
public LocaleResolver localeResolver() {
CookieLocaleResolver localeResolver = new CookieLocaleResolver("clientlanguage");
localeResolver.setCookieMaxAge(Duration.ofSeconds(100000));
return localeResolver;
}
}
// end::snippet[]
framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.java
+48
View File
@@ -0,0 +1,48 @@
/*
* Copyright 2002-present the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolverinterceptor;
import java.util.Map;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.handler.SimpleUrlHandlerMapping;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;
// tag::snippet[]
@Configuration
public class WebConfiguration {
@Bean
public LocaleResolver localeResolver() {
return new CookieLocaleResolver();
}
@Bean
public SimpleUrlHandlerMapping urlMapping() {
SimpleUrlHandlerMapping urlHandlerMapping = new SimpleUrlHandlerMapping();
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("siteLanguage");
urlHandlerMapping.setInterceptors(interceptor);
urlHandlerMapping.setUrlMap(Map.of("/**/*.view", "someController"));
return urlHandlerMapping;
}
}
// end::snippet[]
framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.kt
+35
View File
@@ -0,0 +1,35 @@
/*
* Copyright 2002-present the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolvercookie
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.LocaleResolver
import org.springframework.web.servlet.i18n.CookieLocaleResolver
import java.time.Duration
// tag::snippet[]
@Configuration
class WebConfiguration {
@Bean
fun localeResolver(): LocaleResolver = CookieLocaleResolver("clientlanguage").apply {
setCookieMaxAge(Duration.ofSeconds(100000))
}
}
// end::snippet[]
framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.kt
+44
View File
@@ -0,0 +1,44 @@
/*
* Copyright 2002-present the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolverinterceptor
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.LocaleResolver
import org.springframework.web.servlet.handler.SimpleUrlHandlerMapping
import org.springframework.web.servlet.i18n.CookieLocaleResolver
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor
// tag::snippet[]
@Configuration
class WebConfiguration {
@Bean
fun localeResolver(): LocaleResolver {
return CookieLocaleResolver()
}
@Bean
fun urlMapping() = SimpleUrlHandlerMapping().apply {
setInterceptors(LocaleChangeInterceptor().apply {
paramName = "siteLanguage"
})
/* @chomp:line urlMap = mapOf("/**/*.view" to "someController") */urlMap = mapOf("/**/*.view" to "someController")
}
}
// end::snippet[]
framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.xml
+19
View File
@@ -0,0 +1,19 @@
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
https://www.springframework.org/schema/beans/spring-beans.xsd">
<!-- tag::snippet[] -->
<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">
<constructor-arg index="0" value="clientlanguage"/>
<!-- in seconds. If set to -1, the cookie is not persisted (deleted when browser shuts down) -->
<property name="cookieMaxAge" value="100000"/>
</bean>
<!-- end::snippet[] -->
</beans>
framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.xml
+30
View File
@@ -0,0 +1,30 @@
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
https://www.springframework.org/schema/beans/spring-beans.xsd">
<!-- tag::snippet[] -->
<bean id="localeChangeInterceptor"
class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
<property name="paramName" value="siteLanguage"/>
</bean>
<bean id="localeResolver"
class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/>
<bean id="urlMapping"
class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
<property name="interceptors">
<list>
<ref bean="localeChangeInterceptor"/>
</list>
</property>
<property name="mappings">
<value>/**/*.view=someController</value>
</property>
</bean>
<!-- end::snippet[] -->
</beans>