Localization

ARC9 has a custom localization system mostly inherited from ArcCW. Its main benefit compared to GMod's localization library is being able to localize phrases serverside, hotloading changes, as well as string-to-phrase translation.

Creating a localization file

All localization files should exist in lua/arc9/common/localization/[name]_[lang].lua, where [name] is a string name for your addon and [lang] is the language name (see https://wiki.facepunch.com/gmod/Addon_Localization for a list of valid languages).

The first line should define a global table L. This table will contain all phrases for this localization file. You may fill this table with string keys and string values (in specific cases, non-string values are accepted).

You may optionally also define a global table STL. This table contains "string to phrases", which converts English strings to phrases, and is most commonly used to translate weapon classes and attachment slots. Currently, this system is not used for anything.

Example:

L = {}

L["autostat.damagemax"] = "Close Range Damage"
L["arc9_myatt.printname"] = "Cool Attachment"

STL = {}
STL["Pistol"] = "weaponclass.pistol"

Since this is a Lua file, you may run arbitrary code within the file, although the L global table must be defined and populated.

As convention, please keep all localization file names and key names lowercase.

Localizing Attachments

To translate attachment name and description fields, use the attachment shortname followed by the field name, e.g. arc9_acog.printname. If your addon uses TrueNames, you may also append .true to have a seperate localization for truenames, e.g. arc9_acog.description.true

The following fields are currently supported for attachments:

• PrintName
• CompactName
• Description

You may also add custom Pros and Cons. To do so, add the localization phrase in ATT.Pros or ATT.Cons, and localize it accordingly. The phrase names are completely arbitrary, but we recommend following the convention of [shortname].[pro/con].[number] if it is specific to the attachment.

Example:

-- In arc9_my_acog.lua
ATT.PrintName = "My ACOG"
ATT.Description = "This is so cool!"
ATT.Pros = {
  "arc9_my_acog.pro.1",
  "arc9_my_acog.pro.2",
}
ATT.Cons = {"arc9_my_acog.con.1"}

-- In the localization file
L = {}
L["arc9_my_acog.printname"] = "Mein ACOG"
L["arc9_my_acog.description"] = "Das ist so cool!"

L["arc9_my_acog.pro.1"] = "+100% Epicness"
L["arc9_my_acog.pro.2"] = "+200% Awesomeness"
L["arc9_my_acog.con.1"] = "No random critical hits"

Localizing Settings

To localize a setting in the options menu, use .title and .desc for the name and description respectively. All settings are defined in arc9/client/cl_settings_menu.lua, although you can also simply copy base_en.lua.

Calling Localization Functions

All localization functions are defined in arc9/sahred/sh_i18n.lua. The most notable functions are listed below.

ARC9:GetPhrase(phrase, format)

Translate phrase according to the current language. format is a table to replace placeholders, e.g. {name}: {value} can be replaced with the table {["name"] = "Hello", ["value"] = "World"}. If the phrase does not exist in the current language but exists in English, the English value is returned. If it does not exist in the current language or English, nil is returned.

ARC9:GetPhraseForAtt(att, phrase, format)

Translate a specific field for attachment att. phrase is expected to be a field like PrintName or Description. Internally, this uses GetPhrase but processes the phrase name first.

ARC9:AddSTP(phrase, str, lang)

Add a "String to Phrase", converting a string str to phrase (i.e. "Assault Rifle" to "class.assaultrifle"). The phrase is then used to localize into other languages. Currently unused.

ARC9:AddPhrase(phrase, str, lang)

Adds the specified phrase to language lang with value str after safety checks. Recommended to use language files instead of this function as it is slower.