Texts

The game's texts from its language file: text, cached_text, has_text, number, get_texts.

The game's texts: every string the client shows, from its language file on the GGS CDN.

Usage

from empire_core.texts import text

text("errorCode_120")                 # "This player's level is too low."
text("travelSpeedBonusPerField", 5, 10, lang="de")
number(250000, compact=True)          # "250k"

The language file (about 30k keys in English) is fetched on the first call that asks for a text in that language, cached for 24 hours, and after a failed fetch left alone for five minutes; until then a text falls back to its key, as the client's does. Nothing here touches the network unless a caller asks for a text.

Client: BasicFrameOne.initLocalizationModule (dll line 32213) loads the file into a case-insensitive GlobalizeTextProcessor, read through Localize.text (dll line 3278).

Classes:

Name	Description
LocalizedNumber	A number argument text writes as set here, where a plain number would take the defaults.
PlainText	An argument text fills in as it is: not read as a text id, nor written as a number.

Functions:

Name	Description
fetch_texts	The current language file for lang from the CDN, uncached, keys as the file has them.
get_texts	Every text in lang, keyed by the lower-cased text id; fetched on first use and cached.
fill	template with {0}, {1}, ... replaced by args, each as JavaScript's String() writes it.
number	value as the game writes a number: 1,234.5, or with compact from 100,000 on 250k and 1.5M.
text	The game's text for key in lang with its placeholders filled, or key itself when there is none.
has_text	Whether the language file has a non-empty text for key; fetches it on first use, as text does.
cached_text	Like text, but only from texts already loaded: never fetches and never waits.

Attributes:

Name	Type	Description
CACHE_TTL		Seconds a fetched language file is used before it is fetched again.
RETRY_AFTER_FAILURE		Seconds a failed fetch is not retried, as for the items.
FRACTIONAL_DIGITS		Most fraction digits a number is written with: CastleEnvironmentGlobals.fractionalDigits (bundle line 31469).
ABBREVIATION_THRESHOLD		From this size a compact number is abbreviated: BasicEnvironmentGlobals.abbreviationThreshold, dll line 34330.

logger module-attribute

logger = logging.getLogger(__name__)

LANG_META_URL module-attribute

LANG_META_URL = 'https://langserv.public.ggs-ep.com/12/fr/@metadata'

LANG_DATA_URL module-attribute

LANG_DATA_URL = 'https://langserv.public.ggs-ep.com/12@{version}/{lang}/*'

CACHE_TTL module-attribute

CACHE_TTL = 86400.0

Seconds a fetched language file is used before it is fetched again.

RETRY_AFTER_FAILURE module-attribute

RETRY_AFTER_FAILURE = 300.0

Seconds a failed fetch is not retried, as for the items.

FRACTIONAL_DIGITS module-attribute

FRACTIONAL_DIGITS = 2

Most fraction digits a number is written with: CastleEnvironmentGlobals.fractionalDigits (bundle line 31469).

ABBREVIATION_THRESHOLD module-attribute

ABBREVIATION_THRESHOLD = 100000

From this size a compact number is abbreviated: BasicEnvironmentGlobals.abbreviationThreshold, dll line 34330.

LocalizedNumber dataclass

LocalizedNumber(value: float, compact: bool = False, fractional_digits: int = 0, right_to_left: bool = False)

A number argument text writes as set here, where a plain number would take the defaults.

Client: LocalizedNumberVO (dll line 22822), composed by Localize.number

Attributes:

Name	Type	Description
value	float
compact	bool	Abbreviate from ABBREVIATION_THRESHOLD on, as 250k.
fractional_digits	int	Most fraction digits; -1 for FRACTIONAL_DIGITS.
right_to_left	bool	Put a space before the k or M, as for a right-to-left language.

value instance-attribute

value: float

compact class-attribute instance-attribute

compact: bool = False

Abbreviate from ABBREVIATION_THRESHOLD on, as 250k.

fractional_digits class-attribute instance-attribute

fractional_digits: int = 0

Most fraction digits; -1 for FRACTIONAL_DIGITS.

right_to_left class-attribute instance-attribute

right_to_left: bool = False

Put a space before the k or M, as for a right-to-left language.

PlainText dataclass

PlainText(text: str)

An argument text fills in as it is: not read as a text id, nor written as a number.

For a value the client wraps as shown, such as a player's or an alliance's name.

Client: TextVO (dll line 22901), whose compose returns the string

Attributes:

Name	Type	Description
text	str

text instance-attribute

text: str

fetch_texts

fetch_texts(lang: str = 'en') -> dict[str, str]

The current language file for lang from the CDN, uncached, keys as the file has them.

Raises:

Type	Description
RequestException	The CDN failed

get_texts

get_texts(lang: str = 'en', force_refresh: bool = False) -> Mapping[str, str]

Every text in lang, keyed by the lower-cased text id; fetched on first use and cached.

A failure is not fatal: the texts last fetched (or none) are returned, a warning is logged, and the CDN is not asked again for five minutes. Fresh texts are returned without waiting. Concurrent callers on a cold cache share one download; while a stale copy is being refreshed, other callers get the stale copy. A download in one language never holds up another.

Parameters:

Name	Type	Description	Default
lang	str	Language code (default: "en")	'en'
force_refresh	bool	Fetch from the CDN even when the cached texts are fresh	False

fill

fill(template: str, *args: object) -> str

template with {0}, {1}, ... replaced by args, each as JavaScript's String() writes it.

True goes in as true, 2.0 as 2 and None as null; a placeholder without an argument stays as it is.

This is the client's plain mode, localizeReplacements off, as BasicEnvironmentGlobals (dll line 34326) leaves it; the castle client turns it on, which text follows. fill(get_texts()[key.lower()], ...) fills a text plainly.

Client: doReplacements (dll line 23045), called by GlobalizeTextProcessor.getText (dll line 22948)

number

number(value: float, *, compact: bool = False, fractional_digits: int = -1, right_to_left: bool = False, grouping: bool = True, lang: str = 'en') -> str

value as the game writes a number: 1,234.5, or with compact from 100,000 on 250k and 1.5M.

At most two fraction digits (or fractional_digits), a half rounded up, no trailing zeros; right_to_left puts a space before the k or M. As in the client, both are the caller's to pass, not taken from lang. Only the English and German symbols are known; any other language writes its numbers as English does. A compact number fetches the language file for its k or M on first use, as text does.

Client: Localize.number (dll line 3280) -> GlobalizeTextProcessor.number (dll line 22959), with the castle client's settings (bundle lines 31469 and 31472)

text

text(key: str, *args: object, lang: str = 'en', grouping: bool = True) -> str

The game's text for key in lang with its placeholders filled, or key itself when there is none.

Fills the placeholders as the castle client does: a number argument is written for the language (1,234.5, from 100,000 on 250k; see number), a string that is a text id goes in as that text, a LocalizedNumber as it says and a PlainText as it is. Fetches the language file on first use (see get_texts); a CDN outage gives the key.

Parameters:

Name	Type	Description	Default
key	str	The text id, any case ("errorCode_120", "currency_name_1MinSkip")	required
args	object	Values for the {0}, {1}, ... placeholders	()
lang	str	Language code (default: "en")	'en'
grouping	bool	Group the digits of a number argument by thousands	True

Client: Localize.text (dll line 3278) -> GlobalizeTextProcessor.text (dll line 22952): a missing key reads as the key. Right-to-left reordering is not done.

has_text

has_text(key: str, lang: str = 'en') -> bool

Whether the language file has a non-empty text for key; fetches it on first use, as text does.

Client: Localize.hasText (dll line 3279) -> GlobalizeTextProcessor.hasText (dll line 22945)

cached_text

cached_text(key: str, *args: object, lang: str = 'en', grouping: bool = True) -> str | None

Like text, but only from texts already loaded: never fetches and never waits.

Returns:

Type	Description
str | None	The filled text, or None when lang is not loaded or has no text for key