Module:Tr

From Terraria Wiki
Jump to navigation Jump to search
Lua.svg Documentation The documentation below is transcluded from Module:Tr/doc. (edit | history)

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 database for the given language (Module:Tr/db-ar, Module:Tr/db-bg, etc.) and makes all of its contents available as variables. The variables have the prefix _tr:<lang>:, e.g. {{#var:_tr:it:Fish}} for the Italian (it) translation of "Fish". The page name translations have the prefix _tr:<lang>:link:, e.g. {{#var:_tr:it: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>:, e.g. {{#var:_tr2e:it: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').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').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').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/db-<lang>`).
---The database is cached; see [[Module:Tr/loaddata]] for details about what this
---means.
---@param lang string Language code
---@return table<"main"|"pagename"|"reversed"|"onWikiLangList", 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 language and store
---it as variables (`{{#var:}}`). The variables have the prefix `_tr:<lang>:`,
---e.g. `{{#var:_tr:it:Fish}}` → `Pesce` (Italian translation of "Fish"). The
---page name translations have the prefix `_tr:<lang>:link:`, e.g.
---`{{#var:_tr:it:link:Fish}}` → `Fish/it` (Italian page for "Fish").
---@param frame table Interface to the parser (`mw.frame`)
p.loadData = function(frame)
	local lang = frame.args['lang'] or 'en'
	local database = loadDatabase(lang)
	-- load regular database
	local prefix = '_tr:' .. lang .. ':'
	for termEnglish, termLocalLanguage in pairs(database.main) do
		vardefine(prefix .. termEnglish, termLocalLanguage)
	end
	-- load link database
	prefix = prefix .. 'link:'
	for termEnglish, termLocalLanguage in pairs(database.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: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 .. ':'
	for termLocalLanguage, termEnglish in pairs(database.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 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
---@return string translatedLink
p.translateLink = function(input, lang)
	local database = loadDatabase(lang)
	-- look up the input in the `pagename` database
	local t = database.pagename[input]
	if t then
		-- input exists, return it
		return t
	end
	-- input does not exist in the `pagename` database
	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
	-- 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 database.main[input] or input
end

---For other modules: translate a term from English to the given language.
---This is the equivalent of `{{tr|<input>|lang=<lang>}}`.
---@param input string English term to translate
---@param lang string Language code
---@return string translatedTerm
p.translate = function(input, lang)
	local database = loadDatabase(lang)
	-- look up the term in the database; if that fails, return the input untranslated
	return database.main[input] 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
---@return string englishTerm
p.translate2e = function(input, lang)
	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
	-- look up the term in the database; if that fails, return the input untranslated
	return database.reversed[input] or input
end

return p