Revise localization resolution.

Assisted-By: devx/b3414b50-d642-461b-95a8-8f773c4d087b

Author: samuel-williams-shopify

context/middleware.md

@@ -36,7 +36,7 @@ use Utopia::Redirection::Errors,
 
 ## Localization
 
-The {ruby Utopia::Localization} middleware provides non-intrusive localization on top of the controller and view layers. The middleware uses the `accept-language` header to guess the preferred locale out of the given options. If a request path maps to a resource, that resource is returned. Otherwise, a non-localized request is made.
+The {ruby Utopia::Localization} middleware computes immutable localization preferences from the request path, host, and `accept-language` header. Localization-aware resource middleware, including {ruby Utopia::Static} and {ruby Utopia::Content}, resolves those preferences without invoking controllers more than once. Place the localization middleware before those resources in the middleware stack.
 
 ~~~ ruby
 use Utopia::Localization,
@@ -53,7 +53,7 @@ pages/index.ja.xnode
 pages/index.zh.xnode
 ~~~
 
-You can also access the current locale in the view via {ruby Utopia::Content::Node::Context#localization}.
+You can access the selected locale in a view using `localization.locale`. Controllers can inspect the request preferences using `request.localization`.
 
 ## Controller
 

guides/middleware/readme.md

@@ -36,7 +36,7 @@ use Utopia::Redirection::Errors,
 
 ## Localization
 
-The {ruby Utopia::Localization} middleware provides non-intrusive localization on top of the controller and view layers. The middleware uses the `accept-language` header to guess the preferred locale out of the given options. If a request path maps to a resource, that resource is returned. Otherwise, a non-localized request is made.
+The {ruby Utopia::Localization} middleware computes immutable localization preferences from the request path, host, and `accept-language` header. Localization-aware resource middleware, including {ruby Utopia::Static} and {ruby Utopia::Content}, resolves those preferences without invoking controllers more than once. Place the localization middleware before those resources in the middleware stack.
 
 ~~~ ruby
 use Utopia::Localization,
@@ -53,7 +53,7 @@ pages/index.ja.xnode
 pages/index.zh.xnode
 ~~~
 
-You can also access the current locale in the view via {ruby Utopia::Content::Node::Context#localization}.
+You can access the selected locale in a view using `localization.locale`. Controllers can inspect the request preferences using `request.localization`.
 
 ## Controller
 

lib/utopia/content/document.rb

@@ -30,16 +30,19 @@ class Document < Response
 			# @parameter node [Utopia::Content::Node] The content node.
 			# @parameter request [Utopia::Request] The application request.
 			# @parameter attributes [Hash] The attributes.
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
 			# @returns [Document] The rendered document.
-			def self.render(node, request, attributes)
-				self.new(request, attributes).render!(node, attributes)
+			def self.render(node, request, attributes, localization: request&.localization)
+				self.new(request, attributes, localization: localization).render!(node, attributes)
 			end
 
 			# Initialize a document for a protocol request.
 			# @parameter request [Utopia::Request] The application request.
 			# @parameter attributes [Hash] The attributes.
-			def initialize(request, attributes = {})
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
+			def initialize(request, attributes = {}, localization: request&.localization)
 				@request = request
+				@localization = localization
 
 				@attributes = attributes
 
@@ -101,10 +104,10 @@ def controller
 				@controller ||= Utopia::Controller[request]
 			end
 
-			# Return a localization wrapper for the current request.
-			# @returns [Localization::Wrapper] The localization wrapper.
+			# Return the selected localization preferences for this document.
+			# @returns [Localization::Preferences | Nil] The localization preferences.
 			def localization
-				@localization ||= Utopia::Localization[request]
+				@localization
 			end
 
 			# Parse markup into this document.

lib/utopia/content/links.rb

@@ -19,10 +19,11 @@ class Links
 			# @parameter root [String] The root directory.
 			# @parameter path [Utopia::Path | String] The path.
 			# @parameter locale [String] The locale.
+			# @parameter fallback [Boolean] Whether to return an unlocalized link as a fallback.
 			# @returns [Link | Nil] The resolved link.
-			def self.for(root, path, locale = nil)
+			def self.for(root, path, locale = nil, fallback: true)
 				warn "Using uncached links metadata!"
-				self.new(root).for(path, locale)
+				self.new(root).for(path, locale, fallback: fallback)
 			end
 
 			# Build an index of links for the given path.
@@ -54,9 +55,12 @@ def initialize(root, extension: XNODE_EXTENSION)
 			attr :index_filter
 
 			# Resolve a link for the specified path, which must be a path to a specific link.
-			# 	for(Path["/index"])
-			def for(path, locale = nil)
-				links(path.dirname).lookup(path.last, locale)
+			# @parameter path [Utopia::Path | String] The path.
+			# @parameter locale [String | Nil] The locale.
+			# @parameter fallback [Boolean] Whether to return an unlocalized link as a fallback.
+			# @returns [Link | Nil] The resolved link.
+			def for(path, locale = nil, fallback: true)
+				links(path.dirname).lookup(path.last, locale, fallback: fallback)
 			end
 
 			# Give an index of all links that can be reached from the given path.
@@ -208,16 +212,17 @@ def each(locale)
 				# Lookup.
 				# @parameter name [String] The name.
 				# @parameter locale [String] The locale.
-				# @returns [Link | Nil] The exact locale match, or the unlocalized link as a fallback.
-				def lookup(name, locale = nil)
+				# @parameter fallback [Boolean] Whether to return an unlocalized link as a fallback.
+				# @returns [Link | Nil] The exact locale match, or the unlocalized link when fallback is enabled.
+				def lookup(name, locale = nil, fallback: true)
 					# This allows generic links to serve any locale requested.
 					if links = @named[name]
 						generic_link = nil
 
 						links.each do |link|
 							if link.locale == locale
 								return link
-							elsif link.locale.nil?
+							elsif fallback && link.locale.nil?
 								generic_link = link
 							end
 						end

lib/utopia/content/middleware.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "../middleware"
-require_relative "../localization"
+require_relative "../localization/resolver"
 require_relative "../request"
 require_relative "../response"
 require_relative "../controller/variables"
@@ -22,6 +22,8 @@ module Utopia
 	module Content
 		# A middleware which serves dynamically generated content based on markup files.
 		class Middleware < Protocol::HTTP::Middleware
+			include Localization::Resolver
+			
 			CONTENT_NAMESPACE = "content".freeze
 			UTOPIA_NAMESPACE = "utopia".freeze
 			CONTENT_TAG_NAME = "utopia:content".freeze
@@ -105,12 +107,13 @@ def resolve_link(link)
 			# Respond.
 			# @parameter link [Utopia::Content::Link] The content link.
 			# @parameter request [Utopia::Request] The application request.
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
 			# @returns [Protocol::HTTP::Response] The response.
-			def respond(link, request)
+			def respond(link, request, localization: request.localization)
 				if node = resolve_link(link)
 					attributes = request.variables&.to_hash || {}
 
-					return node.process!(request, attributes)
+					return node.process!(request, attributes, localization: localization)
 				elsif redirect_uri = link[:uri]
 					return Utopia::Response[307, {HTTP::LOCATION => redirect_uri}, []]
 				end
@@ -133,13 +136,18 @@ def call(request)
 					return Utopia::Response[307, {HTTP::LOCATION => path.dirname.join(index_path).to_s}, []]
 				end
 
-				locale = request.locale
-				if link = @links.for(path, locale)
-					if response = self.respond(link, request)
-						return response
+				response = resolve_localized(request) do |localization|
+					locale = localization&.locale
+					
+					if link = @links.for(path, locale, fallback: false)
+						self.respond(link, request, localization: localization)
 					end
 				end
 
+				if response
+					return response
+				end
+				
 				return @delegate.call(request)
 			end
 
@@ -200,10 +208,11 @@ def content_tag(name, node)
 		end
 
 		Traces::Provider(Middleware) do
-			def respond(link, request)
+			def respond(link, request, localization: request.localization)
 				attributes = {
 					"link.key" => link.key,
-					"link.href" => link.href
+					"link.href" => link.href,
+					"link.locale" => localization&.locale,
 				}
 
 				Traces.trace("utopia.content.middleware.respond", attributes: attributes){super}

lib/utopia/content/node.rb

@@ -138,9 +138,10 @@ def call(document, state)
 			# Process the request and return the resulting response.
 			# @parameter request [Utopia::Request] The application request.
 			# @parameter attributes [Hash] The attributes.
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
 			# @returns [Protocol::HTTP::Response] The response.
-			def process!(request, attributes = {})
-				Document.render(self, request, attributes).to_response
+			def process!(request, attributes = {}, localization: request&.localization)
+				Document.render(self, request, attributes, localization: localization).to_response
 			end
 
 			# This is a special context in which a limited set of well defined methods are exposed in the content view.
@@ -167,8 +168,8 @@ def controller
 					document.controller
 				end
 
-				# Return the document's localization wrapper.
-				# @returns [Localization::Wrapper] The localization wrapper.
+				# Return the document's localization preferences.
+				# @returns [Localization::Preferences | Nil] The localization preferences.
 				def localization
 					document.localization
 				end

lib/utopia/exceptions/mailer.rb

@@ -179,7 +179,6 @@ def current_state(request)
 					session: request.session,
 					variables: request.variables,
 					localization: request.localization,
-					current_locale: request.locale,
 					exception: request.exception,
 				}
 			end

lib/utopia/localization.rb

@@ -3,9 +3,12 @@
 # Released under the MIT License.
 # Copyright, 2009-2025, by Samuel Williams.
 
+require_relative "localization/preferences"
+require_relative "localization/resolver"
 require_relative "localization/middleware"
 
 module Utopia
+	# Computes request localization preferences and resolves localized resources.
 	module Localization
 		# Construct localization middleware.
 		# @returns [Localization::Middleware] The localization middleware.