Language and text

phantom.aj.localizationThe screen and sound

The client's text in the player's language.

Scripts and plugins

A script has all of it, as phantom.aj.localization, and so does a plugin, from ctx.phantom(): the SDK runs in the plugin's own frame. Each call is marked with what it needs: game:read for what the area knows and hears, which "game": "read" in the manifest grants, and game:act for doing things in it as the player, which needs "game": "act" (see Permissions).

Overview

Member	What it does	Plugins
addText()	Puts words under a text id in the dictionary the client is showing, and in the player's preferred one when it has one, as a localization pack would have held them: for text the pack the client loaded did not have, such as the name of a den item def added after it loaded (phantom.aj.dens.inventory.addDefinition).	game:act
animalName()	The name behind an animal's coded one (translateAvatarName), such as the Blue|123|4 the server sends for an animal never named: its type and colour, in the player's language.	game:read
current()	The language, locales and country the client holds now, or null before it has a language.	game:read
isReady()	Whether the dictionary is in (hasLocalizations).	game:read
language()	The language the client shows text in now, or null before it has one.	game:read
languageForLocale()	The language the client would pick for a locale (getLanguageIdForLocale), as it does with the player's own as it starts: only the part before the - counts.	game:read
languageId()	The client's own number for a language (LANG_ENG and its siblings), or null with no client.	game:read
petName()	The name behind a pet's coded one (translatePetName), as animalName reads an animal's.	game:read
richText()	One of the client's rich text ids (translateLocalizedId): 9#1234 for words with markup, 9#1234#click#where for a link, as the journey book holds them.	game:read
setLanguage()	Switches the client to another language, as Settings does (LocalizationXtCommManager.requestLocalizationPack), and resolves once its dictionary is in (setLocalizations), with the language as the client then holds it.	game:act
translate()	The words behind one of the client's text ids, in the language showing now (translateIdOnly): the ids journey book facts, HUD labels and report reasons are built from.	game:act
translateAll()	Several ids at once, in the order given, an empty string for each the client has no words for.	game:read
word()	One of the words the client names for itself, in the language showing: the currencies, what it calls a member, and the name it gives a new player.	game:read
words()	Every name word takes.	game:read
onChange()	Hears the language set (currentLanguage's setter): as the client first settles on one, and each time the player picks another.	game:read
onReady()	Hears a dictionary taken in (setLocalizations), with the language it is for: once as the game starts, and again after each setLanguage.	game:read

Methods

addText

methodplugins · game:act

addText(id: number, words: string, options?: ActOptions & { replace?: boolean | undefined; }) => Promise<void>

Puts words under a text id in the dictionary the client is showing, and in the player's preferred one when it has one, as a localization pack would have held them: for text the pack the client loaded did not have, such as the name of a den item def added after it loaded (phantom.aj.dens.inventory.addDefinition). Lasts until the client takes in another pack (setLanguage). Resolves once translate(id) gives the words; throws NOT_READY before the dictionary is in, and REFUSED for an id it has other words under already (unless replace).

Parameters

Name	Type
id	number
words	string
options optional	ActOptions & { replace?: boolean | undefined; }

Returns

Promise<void>

Types

ActOptions

Example

await phantom.aj.localization.addText(9_060_001, 'Star Lamp');

Run in Phantom

animalName

methodplugins · game:read

animalName(coded: string) => Promise<string | null>

The name behind an animal's coded one (translateAvatarName), such as the Blue|123|4 the server sends for an animal never named: its type and colour, in the player's language. A name with no | is the player's own and comes back as it is. Null where the client cannot be asked.

Parameters

Name	Type
coded	string

Returns

Promise<string \| null>

current

methodplugins · game:read

current() => Promise<Localization | null>

The language, locales and country the client holds now, or null before it has a language.

Returns

Promise<Localization \| null>

Types

Localization · Language

isReady

methodplugins · game:read

isReady() => Promise<boolean>

Whether the dictionary is in (hasLocalizations). Until it is, translate gives an empty string for every id, which this tells apart from an id the dictionary has not got.

Returns

Promise<boolean>

language

methodplugins · game:read

language() => Promise<Language | null>

The language the client shows text in now, or null before it has one.

Returns

Promise<Language \| null>

Types

Language

languageForLocale

methodplugins · game:read

languageForLocale(locale: string) => Promise<Language | null>

The language the client would pick for a locale (getLanguageIdForLocale), as it does with the player's own as it starts: only the part before the - counts. Null for one it does not know.

Parameters

Name	Type
locale	string

Returns

Promise<Language \| null>

Types

Language

Example

await phantom.aj.localization.languageForLocale('fr-CA');

Run in Phantom

languageId

methodplugins · game:read

languageId(language: Language) => Promise<number | null>

The client's own number for a language (LANG_ENG and its siblings), or null with no client.

Parameters

Name	Type
language	Language

Returns

Promise<number \| null>

Types

Language

petName

methodplugins · game:read

petName(coded: string) => Promise<string | null>

The name behind a pet's coded one (translatePetName), as animalName reads an animal's.

Parameters

Name	Type
coded	string

Returns

Promise<string \| null>

richText

methodplugins · game:read

richText(coded: string) => Promise<LocalizedText>

One of the client's rich text ids (translateLocalizedId): 9#1234 for words with markup, 9#1234#click#where for a link, as the journey book holds them. An id it has no words for comes back as its own text, as the client shows it.

Parameters

Name	Type
coded	string

Returns

Promise<LocalizedText>

Types

LocalizedText

setLanguage

methodplugins · game:act

setLanguage(language: Language, options?: ActOptions) => Promise<Localization>

Switches the client to another language, as Settings does (LocalizationXtCommManager.requestLocalizationPack), and resolves once its dictionary is in (setLocalizations), with the language as the client then holds it. The client rebuilds the HUD from it over the next frames. 30 seconds by default: the pack is downloaded.

Parameters

Name	Type
language	Language
options optional	ActOptions

Returns

Promise<Localization>

Types

Localization · Language · ActOptions

translate

methodplugins · game:act

translate(id: number, options?: TranslateOptions) => Promise<string>

The words behind one of the client's text ids, in the language showing now (translateIdOnly): the ids journey book facts, HUD labels and report reasons are built from. An id the dictionary has not got, or not yet, is an empty string.

Parameters

Name	Type
id	number
options optional	TranslateOptions

Returns

Promise<string>

Types

TranslateOptions

Example

await phantom.aj.localization.translate(11097);
await phantom.aj.localization.translate(11432, { values: [250] });

Run in Phantom

translateAll

methodplugins · game:read

translateAll(ids: readonly number[], options?: { preferred?: boolean | undefined; }) => Promise<string[]>

Several ids at once, in the order given, an empty string for each the client has no words for.

Parameters

Name	Type
ids	readonly number[]
options optional	{ preferred?: boolean | undefined; }

Returns

Promise<string[]>

Example

const [gems, diamonds] = await phantom.aj.localization.translateAll([11097, 11103]);

Run in Phantom

word

methodplugins · game:read

word(name: "gems" | "tickets" | "diamonds" | "gem" | "crystals" | "diamond" | "members" | "crystal" | "ticket" | "newJammerName") => Promise<string>

One of the words the client names for itself, in the language showing: the currencies, what it calls a member, and the name it gives a new player. words() lists them.

Parameters

Name	Type
name	"gems" | "tickets" | "diamonds" | "gem" | "crystals" | "diamond" | "members" | "crystal" | "ticket" | "newJammerName"

Returns

Promise<string>

Example

console.log(`1,200 ${await phantom.aj.localization.word('gems')}`);

Run in Phantom

words

methodplugins · game:read

words() => ("gems" | "tickets" | "diamonds" | "gem" | "crystals" | "diamond" | "members" | "crystal" | "ticket" | "newJammerName")[]

Every name word takes.

Returns

("gems" \| "tickets" \| "diamonds" \| "gem" \| "crystals" \| "diamond" \| "members" \| "crystal" \| "ticket" \| "newJammerName")[]

Events

onChange

eventplugins · game:read

onChange(listener: (language: Language) => void) => () => void

Hears the language set (currentLanguage's setter): as the client first settles on one, and each time the player picks another. The dictionary follows a moment later: onReady hears it.

Parameters

Name	Type
listener	(language: Language) => void

Returns

() => void. Call it to stop listening.

Types

Language

onReady

eventplugins · game:read

onReady(listener: (language: Language) => void) => () => void

Hears a dictionary taken in (setLocalizations), with the language it is for: once as the game starts, and again after each setLanguage. Only after it does translate give words.

Parameters

Name	Type
listener	(language: Language) => void

Returns

() => void. Call it to stop listening.

Types

Language

Types

The types the calls above take and give, with every field. Import any of them in a plugin from @phantomclient/plugin/sdk, or use them as they are in a script.

Localization

The client's language as current() reads it.

Field	Type
language	Language	What the client shows text in now (currentLanguage).
account	Language	The account's own language (accountLanguage), taken from the player's locale as the client starts; it does not follow a language picked in Settings. none where the client could not tell.
ready	boolean	Whether the dictionary is in (hasLocalizations): before it, every id translates to nothing.
sortingLocale	string | null	The locale the client sorts by (localeForSorting), ready for Intl.Collator; null for none.
numberLocale	string | null	The locale the client writes numbers by, ready for Intl.NumberFormat; null for none.
country	string | null	The country the client was told the player is in (_countryCode), such as GB.
reversed	boolean	Whether the language writes a date day first, as isCurrLanguageReversed says.

Language

One of the languages the client can show, by the name its LANG_* number stands for.

type Language = 'english' | 'spanish' | 'portuguese' | 'french' | 'german' | 'none'

TranslateOptions

How translate reads an id.

Field	Type
values optional	readonly (string | number)[] | undefined	Values for the id's %s placeholders, in order (translateIdAndInsertOnly). The client refuses an id with a different number of them, which throws REFUSED.
preferred optional	boolean | undefined	From the player's own preferred dictionary rather than the one showing (translatePreferredIdOnly), as a jam-a-gram's phrase is shown. Not with values.

LocalizedText

A translated piece of rich text, as translateLocalizedId gives one.

Field	Type
text	string	The words, or the coded id itself where the dictionary has none for it.
isHtmlNormal	boolean	Shown as HTML, for the markup the client's own localized text carries.
isHtmlClick	boolean	HTML that is also a link; link says where to.
link	string | null

ActOptions

How long something that acts may take, and what may end it first.

Field	Type
timeoutMs optional	number | undefined	10 seconds by default.
signal optional	AbortSignal | undefined