Class: Utopia::Localization

Inherits:
Object
  • Object
show all
Defined in:
lib/utopia/localization.rb

Overview

A middleware which attempts to find localized content.

Defined Under Namespace

Classes: Wrapper

Constant Summary collapse

RESOURCE_NOT_FOUND = 
[400, {}, []].freeze
HTTP_ACCEPT_LANGUAGE = 
'HTTP_ACCEPT_LANGUAGE'.freeze
LOCALIZATION_KEY = 
'utopia.localization'.freeze
CURRENT_LOCALE_KEY = 
'utopia.localization.current_locale'.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(app, locales:, default_locale: nil, default_locales: nil, hosts: {}, ignore: []) ⇒ Localization

Returns a new instance of Localization.

Parameters:

  • locales (Array<String>) —

    An array of all supported locales.

  • default_locale (String) (defaults to: nil) —

    The default locale if none is provided.

  • default_locales (String) (defaults to: nil) —

    The locales to try in order if none is provided.

  • hosts (Hash<Pattern, String>) (defaults to: {}) —

    Specify a mapping of the HTTP_HOST header to a given locale.

  • ignore (Array<Pattern>) (defaults to: []) —

    A list of patterns matched against PATH_INFO which will not be localized.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/utopia/localization.rb', line 77

def initialize(app, locales:, default_locale: nil, default_locales: nil, hosts: {}, ignore: [])
	@app = app
	
	@all_locales = HTTP::Accept::Languages::Locales.new(locales)
	
	# Locales here are represented as an array of strings, e.g. ['en', 'ja', 'cn', 'de'] and are used in order if no locale is specified by the user.
	unless @default_locales = default_locales
		if default_locale
			@default_locales = [default_locale, nil]
		else
			# We append nil, i.e. no localization.
			@default_locales = @all_locales.names + [nil]
		end
	end
	
	@default_locale = default_locale || @default_locales.first
	
	unless @default_locales.include? @default_locale
		@default_locales.unshift(@default_locale)
	end
	
	# Select a localization based on a request host name:
	@hosts = hosts
	
	@ignore = ignore || options[:nonlocalized]
	
	@methods = methods
end

Instance Attribute Details

#all_locales ⇒ Object (readonly)

Returns the value of attribute all_locales.



118
119
120
 
# File 'lib/utopia/localization.rb', line 118

def all_locales
  @all_locales
end

#default_locale ⇒ Object (readonly)

Returns the value of attribute default_locale.



119
120
121
 
# File 'lib/utopia/localization.rb', line 119

def default_locale
  @default_locale
end

Class Method Details

.[](request) ⇒ Object 



62
63
64
 
# File 'lib/utopia/localization.rb', line 62

def self.[] request
	Wrapper.new(request.env)
end

Instance Method Details

#browser_preferred_locales(env) ⇒ Object 



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/utopia/localization.rb', line 167

def browser_preferred_locales(env)
	accept_languages = env[HTTP_ACCEPT_LANGUAGE]
	
	# No user prefered languages:
	return [] unless accept_languages
	
	# Extract the ordered list of languages:
	languages = HTTP::Accept::Languages.parse(accept_languages)
	
	# Returns available languages based on the order languages:
	return @all_locales & languages
rescue HTTP::Accept::ParseError
	# If we fail to parse the browser Accept-Language header, we ignore it (silently).
	return []
end

#call(env) ⇒ Object 



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/utopia/localization.rb', line 207

def call(env)
	# Pass the request through if it shouldn't be localized:
	return @app.call(env) unless localized?(env)
	
	env[LOCALIZATION_KEY] = self
	
	response = nil
	
	# We have a non-localized request, but there might be a localized resource. We return the best localization possible:
	preferred_locales(env) do |localized_env|
		# puts "Trying locale: #{localized_env[CURRENT_LOCALE_KEY]}: #{localized_env[Rack::PATH_INFO]}..."
		
		response = @app.call(localized_env)
		
		break unless response[0] >= 400
	end
	
	return vary(env, response)
end

#freeze ⇒ Object 



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/utopia/localization.rb', line 106

def freeze
	return self if frozen?
	
	@all_locales.freeze
	@default_locales.freeze
	@default_locale.freeze
	@hosts.freeze
	@ignore.freeze
	
	super
end

#host_preferred_locales(env) ⇒ Object 



147
148
149
150
151
152
153
154
 
# File 'lib/utopia/localization.rb', line 147

def host_preferred_locales(env)
	http_host = env[Rack::HTTP_HOST]
	
	# Yield all hosts which match the incoming http_host:
	@hosts.each do |pattern, locale|
		yield locale if http_host[pattern]
	end
end

#localized?(env) ⇒ Boolean

Returns:

  • (Boolean) 


183
184
185
186
187
188
189
 
# File 'lib/utopia/localization.rb', line 183

def localized?(env)
	# Ignore requests which match the ignored paths:
	path_info = env[Rack::PATH_INFO]
	return false if @ignore.any? { |pattern| path_info[pattern] != nil }
	
	return true
end

#preferred_locales(env) ⇒ Object 



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/utopia/localization.rb', line 121

def preferred_locales(env)
	return to_enum(:preferred_locales, env) unless block_given?
	
	# Keep track of what locales have been tried:
	locales = Set.new
	
	host_preferred_locales(env) do |locale|
		yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
	end
	
	request_preferred_locale(env) do |locale, path|
		# We have extracted a locale from the path, so from this point on we should use the updated path:
		env = env.merge(Rack::PATH_INFO => path.to_s)
		
		yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
	end
	
	browser_preferred_locales(env).each do |locale|
		yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
	end
	
	@default_locales.each do |locale|
		yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
	end
end

#request_preferred_locale(env) ⇒ Object 



156
157
158
159
160
161
162
163
164
165
 
# File 'lib/utopia/localization.rb', line 156

def request_preferred_locale(env)
	path = Path[env[Rack::PATH_INFO]]
	
	if request_locale = @all_locales.patterns[path.first]
		# Remove the localization prefix:
		path.delete_at(0)
		
		yield request_locale, path
	end
end

#vary(env, response) ⇒ Object

Set the Vary: header on the response to indicate that this response should include the header in the cache key.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/utopia/localization.rb', line 192

def vary(env, response)
	headers = response[1].to_a
	
	# This response was based on the Accept-Language header:
	headers << ['Vary', 'Accept-Language']
	
	# Althought this header is generally not supported, we supply it anyway as it is useful for debugging:
	if locale = env[CURRENT_LOCALE_KEY]
		# Set the Content-Location to point to the localized URI as requested:
		headers['Content-Location'] = "/#{locale}" + env[Rack::PATH_INFO]
	end
	
	return response
end