Module:Dictionary

Overview

See {{Translate}} for how/when to use and more documentation.

p.translate

Translates a given key from Data:Dictionary. Manual invocation should only be used when additional parameters are required, such as {{Update layout}}, where the DISPLAYTITLE is generated using a translation key with expected parameters.

For normal usage, use the basic template.

Function parameters

• key – translation key (required).
• Language-specific:
  • lang_code_override (optional, named parameter) – language code overriding the automatic detection. See Data:LangCodes.json.
  • fallback_str (optional, named parameter) – value returned only if translation is missing. If set to empty string or nil, fallback will be empty (useful for detecting missing translations).

Examples

{{#invoke:Dictionary|translate|Update history}} Output: Update history

{{#invoke:Dictionary|translate|Updates|lang_code_override=pt-br}} Output: Atualizações

{{#invoke:Dictionary|translate|Update history|fallback_str=Custom fallback text.}} Output: Custom fallback text.

---

local p = {}

-- Localize core functions to bypass global table lookups (_G)
local type = type
local tonumber = tonumber
local string_format = string.format
local string_gsub = string.gsub

-- Load data data sets once at module initialization
local dictionary_data = mw.loadJsonData("Data:Dictionary")
local lang_codes_set = mw.loadJsonData("Data:LangCodes.json")

-- Persistent cache across multiple #invoke calls on the same page
local cached_lang_code = nil
local current_frame = nil

-- Forward declare local function for speed and scope
local function get_lang_code()
	if cached_lang_code then 
		return cached_lang_code 
	end

	-- mw.title.getCurrentTitle() is expensive; we cache the result
	local title = mw.title.getCurrentTitle()
	local lang_code = title.fullText:match(".*/(.-)$")

	if not lang_code or not lang_codes_set[lang_code] then
		cached_lang_code = 'en'
	else
		cached_lang_code = lang_code
	end

	return cached_lang_code
end

-- Used by [[Template:Translate]]
p.translate = function(key, lang_code_override, fallback_str, vars)
	local is_frame = false
	local args

	-- Handle the case where it's called via #invoke (i.e., from wikitext)
	if type(key) == "table" and key.args then
		is_frame = true
		current_frame = key
		args = current_frame.args
		key = args[1]
		lang_code_override = args["lang_code_override"]
		fallback_str = args["fallback_str"]
	end

	local lang_code = lang_code_override
	if not lang_code or lang_code == '' then
		lang_code = get_lang_code()
	end

	local translations = dictionary_data[key]
	if not translations then 
		return string_format("Key '%s' is not in Data:Dictionary", key or 'nil') 
	end

	local translation = translations[lang_code]

	if not translation then
		-- Determine the appended tooltip
		local needs_translation_expand = ''
		if key ~= 'MissingValveTranslationTooltip' and key ~= 'NeedsTranslationTooltip' and key ~= 'NotesNeedsTranslation' then
			local template_args = {}
			if key == 'Notes' then
				template_args[1] = 'NotesNeedsTranslation'
			end
			
			-- Reuse the frame context to avoid unnecessary boundary shifts
			if not current_frame then
				current_frame = mw.getCurrentFrame()
			end
			needs_translation_expand = current_frame:expandTemplate{title = 'NeedsTranslationTooltip', args = template_args}
		end

		-- Determine the fallback string to use
		if fallback_str == 'en' or not fallback_str then
			translation = translations["en"]
		else
			translation = fallback_str
			
			-- Only fallback to key if explicit fallback_str fails
			if not translation then
				translation = key
			end
		end

		-- Add the tooltip
		if translation and translation ~= '' then
			translation = translation .. needs_translation_expand
		end
	end

	-- Variable Substitution Optimization
	if translation then
		if is_frame then
			-- Single-pass regex replacement directly from frame arguments (Zero allocations)
			translation = string_gsub(translation, "{{{(%d+)}}}", function(n)
				return args[tonumber(n) + 1] or ""
			end)
		elseif vars then
			-- Single-pass regex replacement for standard Lua table arrays
			translation = string_gsub(translation, "{{{(%d+)}}}", function(n)
				return vars[tonumber(n)] or ""
			end)
		end
	end

	return translation
end

return p