Module:wikimedia languages

---

The following documentation is located at Module:wikimedia languages/documentation. ^[edit]

Useful links: subpage list • links • transclusions • testcases • sandbox

This module is used to retrieve and manage Wikimedia languages.

Until phab:T10217 is fixed there is a mis-match between the codes used by ISO 639, and those used by Wikimedia, for certain languages. There are also some languages that are recognised as distinct by Wikimedia, but are combined into other languages on Wiktionary (see Wiktionary:Language treatment). This module aids in mapping between the two.

The information itself is stored in Module:wikimedia languages/data. This modules should not be used directly by any other module, the data should only be accessed through the functions provided by Module:wikimedia languages.

Finding and retrieving languages

The module exports a number of functions that are used to find languages.

getByCode

getByCode(code)

Finds the Wikimedia language whose code matches the one provided. If it exists, it returns a WikimediaLanguage object representing the language. Otherwise, it returns nil.

getByCodeWithFallback

getByCodeWithFallback(code)

This does the same as getByCode. However, if that function returns nil, then the regular language with that code is retrieved, if it exists. The function then returns the first element of the list returned by a call to the :getWikimediaLanguages() method of that language. If that method returns no elements, the function returns nil.

Language objects' getWikimediaLanguages method

The :getWikimediaLanguages() method is available on regular Language objects (as returned by Module:languages). This method returns WikimediaLanguage objects that represent that language outside Wiktionary.

Comparison

The differences between the various ways of retrieving languages can be seen here, using some examples.

Code	Module:languages .getByCode	Module:languages .getByCode():getWikimediaLanguages()	Module:wikimedia languages .getByCode	Module:wikimedia languages .getByCodeWithFallback	Notes
fr	fr/French	fr/French	fr/French	fr/French	Code used by both Wikimedia and Wiktionary.
bs	nil	()	bs/Bosnian	bs/Bosnian	Code used only by Wikimedia, not Wiktionary.
sh	sh/Serbo-Croatian	sh/Serbo-Croatian bs/Bosnian hr/Croatian sr/Serbian	sh/Serbo-Croatian	sh/Serbo-Croatian	Code used by both Wikimedia and Wiktionary. Module:wikimedia languages returns sh as that is a valid Wikimedia code. :getWikimediaLanguages() maps the code to multiple possible Wikimedia codes.
cmn	cmn/Mandarin	zh/Chinese	nil	zh/Chinese	Code is used only by Wiktionary, not Wikimedia. The code is mapped by :getWikimediaLanguages() to the equivalent Wikimedia code zh.
wym	wym/Vilamovian	nil	nil	nil	Code is used only by Wiktionary, not Wikimedia. The code is not mapped onto another by :getWikimediaLanguages(), so nil is returned.

WikimediaLanguage objects

A WikimediaLanguage object is returned from one of the functions above. It is a Lua representation of a Wikimedia language and the data associated with it. It has a number of methods that can be called on it, using the : syntax. For example:

local m_wmlanguages = require("Module:wikimedia languages")
local lang = m_wmlanguages.getByCode("bs")
local name = lang:getCanonicalName()
-- "name" will now be "Bosnian"

Language:getCode

:getCode()

Returns the language code of the language. Example: "fr" for French.

Language:getCanonicalName

:getCanonicalName()

Returns the canonical name of the language. This is the name used to represent that language on Wiktionary. Example: "French" for French.

Language:getAllNames

:getAllNames()

Returns a table of all names that the language is known by, including the canonical name. The names are not guaranteed to be unique, sometimes more than one language is known by the same name. Example: {"French", "Modern French"} for French.

Language:getType

:getType()

Returns "Wikimedia".

Language:getWiktionaryLanguage

:getWiktionaryLanguage()

Returns a Language object (see Module:languages) that represents the Wiktionary-native language that is equivalent to this Wikimedia language. In most cases, this will be the same code and name as the original Wikimedia language, but a few of them differ.

Note that unlike the :getWikimediaLanguages method in on Language objects, this only returns a single object. This is done so that the application of tags and script formatting is unambiguous.

Language:getData

:getData()

This function is not for use in entries or other content pages.

Returns a blob of data about the language. The format of this blob is undocumented, and perhaps unstable; it's intended for things like the module's own unit-tests, which are "close friends" with the module and will be kept up-to-date as the format changes.

local export = {}

local languages_module = "Module:languages"
local wm_languages_data_data_module = "Module:wikimedia languages/data"

local get_by_code -- Defined below.
local gmatch = string.gmatch
local is_known_language_tag = mw.language.isKnownLanguageTag
local make_object -- Defined below.
local require = require
local setmetatable = setmetatable
local type = type

--[==[
Loaders for functions in other modules, which overwrite themselves with the target function when called. This ensures modules are only loaded when needed, retains the speed/convenience of locally-declared pre-loaded functions, and has no overhead after the first call, since the target functions are called directly in any subsequent calls.]==]
	local function get_lang(...)
		get_lang = require(languages_module).getByCode
		return get_lang(...)
	end
	
	local function get_lang_data_module_name(...)
		get_lang_data_module_name = require(languages_module).getDataModuleName
		return get_lang_data_module_name(...)
	end

--[==[
Loaders for objects, which load data (or some other object) into some variable, which can then be accessed as "foo or get_foo()", where the function get_foo sets the object to "foo" and then returns it. This ensures they are only loaded when needed, and avoids the need to check for the existence of the object each time, since once "foo" has been set, "get_foo" will not be called again.]==]
	local wm_languages_data
	local function get_wm_languages_data()
		wm_languages_data, get_wm_languages_data = mw.loadData(wm_languages_data_data_module), nil
		return wm_languages_data
	end

local WikimediaLanguage = {}
WikimediaLanguage.__index = WikimediaLanguage

function WikimediaLanguage:getCode()
	return self._code
end

function WikimediaLanguage:getCanonicalName()
	return self._data[1]
end

--function WikimediaLanguage:getAllNames()
--	return self._data.names
--end

--[==[Returns a table of types as a lookup table (with the types as keys).

Currently, the only possible type is {Wikimedia language}.]==]
function WikimediaLanguage:getTypes()
	local types = self._types
	if types == nil then
		types = {["Wikimedia language"] = true}
		local rawtypes = self._data.type
		if rawtypes then
			for t in gmatch(rawtypes, "[^,]+") do
				types[t] = true
			end
		end
		self._types = types
	end
	return types
end

--[==[Given a list of types as strings, returns true if the Wikimedia language has all of them.]==]
function WikimediaLanguage:hasType(...)
	local args, types = {...}, self:getTypes()
	for i = 1, #args do
		if not types[args[i]] then
			return false
		end
	end
	return true
end

function WikimediaLanguage:getWiktionaryLanguage()
	local object = self._wiktionaryLanguageObject
	if object == nil then
		object = get_lang(self._data.wiktionary_code, nil, "allow etym")
		self._wiktionaryLanguageObject = object
	end
	return object
end

-- Do NOT use this method!
-- All uses should be pre-approved on the talk page!
function WikimediaLanguage:getData()
	return self._data
end

function export.makeObject(code, data)
	local data_type = type(data)
	if data_type ~= "table" then
		error(("bad argument #2 to 'makeObject' (table expected, got %s)"):format(data_type))
	end
	return setmetatable({_data = data, _code = code}, WikimediaLanguage)
end
make_object = export.makeObject

function export.getByCode(code)
	-- Only accept codes the software recognises.
	if not is_known_language_tag(code) then
		return nil
	end
	local data = (wm_languages_data or get_wm_languages_data())[code]
	-- If there is no specific Wikimedia code, then "borrow" the information
	-- from the general Wiktionary language code.
	local name, wiktionary_code
	if data ~= nil then
		name, wiktionary_code = data[1], data.wiktionary_code
		if not (name == nil or wiktionary_code == nil) then
			return make_object(code, data)
		end
	end
	-- Get the associated Wiktionary language, using the wiktionary_code key or
	-- else the input code.
	if wiktionary_code == nil then
		wiktionary_code = code
	end
	local lang = get_lang(wiktionary_code, nil, "allow etym", "allow family")
	if lang ~= nil then
		return make_object(code, {
			name == nil and lang:getCanonicalName() or name,
			wiktionary_code = wiktionary_code,
		})
	end
	-- If there's no Wiktionary language for the relevant code, throw an error.
	-- This should never happen.
	local msg, arg3
	if data == nil then
		msg = "code '%s' is a valid Wikimedia language code, but there is no corresponding data in [[%s]] or [[Module:%s]] or [[Module:families/data]]"
	elseif wiktionary_code ~= code then
		msg = "code '%s' is a valid Wikimedia language code and has data in [[%s]], but its 'wiktionary_code' key '%s' is not valid"
		arg3 = wiktionary_code
	else
		msg = "code '%s' is a valid Wikimedia language code and has data in [[%s]], but no corresponding data in [[Module:%s]] or [[Module:families/data]]"
	end
	error(msg:format(code, wm_languages_data_data_module, arg3 or get_lang_data_module_name(code)))
end
get_by_code = export.getByCode

function export.getByCodeWithFallback(code)
	local object = get_by_code(code)
	if object ~= nil then
		return object
	end
	local lang = get_lang(code, nil, "allow etym")
	return lang ~= nil and lang:getWikimediaLanguages()[1] or nil
end

return export