Module:Tr

This module facilitates translation of game terms and wiki page names between English and other languages. It provides the functionality of the {{tr}} template and can also be used from within other modules.

The module can be called from wikitext with the following functions:

• {{#invoke:Tr| loadData | <language> }}

This function is generally only intended for {{tr}}. It loads the translation databases for the given language (Module:Tr/db-en, Module:Tr/db-ru, etc. and Module:Tr/vanilla-en, Module:Tr/vanilla-ru, ) and makes all of its contents available as variables. The variables have the prefix _tr:<lang>:mod: or _tr:<lang>:vanilla:, e.g. {{#var:_tr:it:vanilla:Fish}} for the Italian (it) translation of "Fish". The page name translations have the prefix _tr:<lang>:vanilla-link: or _tr:<lang>:mod-link:, e.g. {{#var:_tr:it:vanilla-link:Fish}} for the Italian page for "Fish".

• {{#invoke:Tr| loadData2e | <language> }}

This function is generally only intended for {{tr2e}}. It loads the reversed translation database for the given language (translation of terms from the language to English) and makes all of its contents available as variables. The variables have the prefix _tr2e:<lang>:vanilla: or _tr2e:<lang>:mod:, e.g. {{#var:_tr2e:it:vanilla:Pesce}} for the English translation of the Italian (it) term "Pesce".

• {{#invoke:Tr| purge | <language> }}

Purges the cache of the translation database for the given language. This is necessary after making a change to the database. See Module:Tr/loaddata for more details.

The module can be called from another module with the following functions:

• require('Module:Tr').translate('<englishTerm>', '<language>')

Returns the translation of the given term to the given language. This is the Lua equivalent of {{tr|<englishTerm>|lang=<language>}}.

• require('Module:Tr').translate('<englishTerm>', '<language>', true)

Returns the translation of the given term to the given language. This is the Lua equivalent of {{tr|<englishTerm>|lang=<language>|vanilla=y}}.

• require('Module:Tr').translateLink('<englishLink>', '<language>')

Returns the page name translation of the given term to the given language. This is the Lua equivalent of {{tr|<englishLink>|lang=<language>|link=y}}.

• require('Module:Tr').translateLink('<englishLink>', '<language>', true)

Returns the page name translation of the given term to the given language. This is the Lua equivalent of {{tr|<englishLink>|lang=<language>|link=y|vanilla=y}}.

• require('Module:Tr').translate2e('<term>', '<language>')

Returns the translation of the given term from the given language to English. This is the Lua equivalent of {{tr2e|<term>|lang=<language>}}.

• require('Module:Tr').translate2e('<term>', '<language>', true)

Returns the translation of the given term from the given language to English. This is the Lua equivalent of {{tr2e|<term>|lang=<language>|vanilla=y}}.

• require('Module:Tr').purge('<language>')

Purges the cache of the translation database for the given language. This is necessary after making a change to the database. See Module:Tr/loaddata for more details.

---

--------------------------------------------------------------------------------
--
-- =============================================================================
--
-- Module:Tr
--
-- Translations of game terms and page names between English and other languages
--
-- =============================================================================
--
-- Code annotations:
-- This module is documented according to LuaCATS (Lua Comment and Type System).
-- LuaCATS comments are prefixed with three dashes (---) and use Markdown syntax.
-- For a full list of annotations, see the following link:
-- https://luals.github.io/wiki/annotations/
--
--------------------------------------------------------------------------------


local vardefine = mw.ext.VariablesLua.vardefine

---Load the translation database for the given language (`Module:Tr/loaddata-<lang>`).
---@param lang string Language code
---@return table
local function loadDatabase(lang)
	return mw.loadData('Module:Tr/loaddata-' .. lang)
end


--------------------------------------------------------------------------------
---Main return object
local p = {}

---For `{{tr}}`: load the translation database for the given mod and store
---it as variables (`{{#var:}}`). The variables have the prefix `_tr:<lang>:`,
---e.g. `{{#var:_tr:ru:Call Upon The Eggs}}` → `Призыв к Яйцам` (Russian translation of this term).
---@param frame table Interface to the parser (`mw.frame`)
p.loadData = function(frame)
	local lang = frame.args['lang'] or ''
	local database = loadDatabase(lang)
	local prefix = '_tr:' .. lang .. ':vanilla'
	-- load database, but not in case the language is English
	-- vanilla
	for termEnglish, termLocalLanguage in pairs(database.vanilla.main) do
		vardefine(prefix .. ':' .. termEnglish, termLocalLanguage)
	end
	prefix = prefix .. '-link'
	for termEnglish, termLocalLanguage in pairs(database.vanilla.pagename) do
		vardefine(prefix .. ':' .. termEnglish, termLocalLanguage)
	end
	-- mod
	prefix = '_tr:' .. lang .. ':mod'
	for termEnglish, termLocalLanguage in pairs(database.mod.main) do
		vardefine(prefix .. ':' .. termEnglish, termLocalLanguage)
	end
	prefix = prefix .. '-link'
	for termEnglish, termLocalLanguage in pairs(database.mod.pagename) do
		vardefine(prefix .. ':' .. termEnglish, termLocalLanguage)
	end
end

---For `{{tr2e}}`: load the reversed translation database for the given language
---and store it as variables (`{{#var:}}`). The variables have the prefix `_tr2e:<lang>:`,
---e.g. `{{#var:_tr2e:it:vanilla:Pesce}}` → `Fish` (Italian translation of "Fish").
---@param frame table Interface to the parser (`mw.frame`)
p.loadData2e = function(frame)
	local lang = frame.args['lang'] or 'en'
	local database = loadDatabase(lang)
	local prefix = '_tr2e:' .. lang .. ':vanilla:'
	for termLocalLanguage, termEnglish in pairs(database.vanilla.reversed) do
		vardefine(prefix .. termLocalLanguage, termEnglish)
	end
	prefix = '_tr2e:' .. lang .. ':mod:'
	for termLocalLanguage, termEnglish in pairs(database.mod.reversed) do
		vardefine(prefix .. termLocalLanguage, termEnglish)
	end
end

---Purge the cache of the translation database for the given language. See
---[[Module:Tr/loaddata]] for details about what this means.
---Invoke from wikitext or from another module.
---@param frame table Interface to the parser (`mw.frame`)
p.purge = function(frame)
	local lang
	if frame == mw.getCurrentFrame() then
		lang = frame.args['lang']
	else
		lang = frame
	end
	lang = lang or 'en'
	require('Module:Tr/loaddata').purge(lang)
end


---For other modules: translate a term from the mod.
---This is the equivalent of `{{tr|<input>|lang=<lang>}}`.
---If there is no such term in mod database then it looks up
---in the database for the original game.
---@param input string English term to translate
---@param lang string Language code
---@param vanilla boolean Vanilla terms only
---@return string translatedTerm
p.translate = function(input, lang, vanilla)
	if lang == 'en' then
		return input
	end
	
	local database = loadDatabase(lang)
	local result
	
	if vanilla then
		result = database.vanilla.main[input]
	else
		result = database.mod.main[input] or database.vanilla.main[input]
	end
	
	-- look up the term in the database; if that fails, return the input untranslated
	return result or input
end

---For other modules: translate a page name from English to the given language.
---This is the equivalent of `{{tr|<input>|lang=<lang>|link=y}}`.
---@param input string English page name to translate
---@param lang string Language code
---@param vanilla boolean Vanilla terms only
---@return string translatedLink
p.translateLink = function(input, lang, vanilla)
	local database = loadDatabase(lang)
	
	-- for onWiki languages
	if database.onWikiLangList[lang] then
		-- the target language is "onWiki", so the link translation is very simple
		-- and always the same: `<English page name>/<language code>` (e.g.
		-- `Fish/it` for the Italian link translation of `Fish`)
		return input .. '/' .. lang
	end
	
	-- look up the input in the `pagename` database
	if vanilla then
		local t = database.vanilla.pagename[input]
	else
		local t = database.mod.pagename[input] or database.vanilla.pagename[input]
	end
	if t then
		-- input exists, return it
		return t
	end
	-- input does not exist in the `pagename` database
	
	
	if vanilla then
		t = database.vanilla.main[input]
	else
		t = database.mod.main[input] or database.vanilla.main[input]
	end
	-- the target language is "offWiki", so fallback: look up the input in the
	-- regular translation database
	-- if that also fails, return the input untranslated
	return t or input
end

---For other modules: translate a term from the given language to English.
---This is the equivalent of `{{tr2e|<input>|lang=<lang>}}`.
---@param input string Term to translate
---@param lang string Language code
---@param vanilla boolean Vanilla terms only
---@return string englishTerm
p.translate2e = function(input, lang, vanilla)
	local database = loadDatabase(lang)
	if database.onWikiLangList[lang] then
		-- the input language is "onWiki", so first try to reverse the link
		-- translation (e.g. `Fish/it` with Italian as the input language is
		-- `Fish` in English)
		local result, count = string.gsub(input, '/' .. lang .. '$', '')
		if count then
			return result
		end
	end
	
	if vanilla then
		local t = database.vanilla.reversed[input]
	else
		local t = database.mod.reversed[input] or database.vanilla.reversed[input]
	end
	-- look up the term in the database; if that fails, return the input untranslated
	return t or input
end

return p