Package com.ultikits.ultitools.interfaces

Interface Localized

All Known Implementing Classes:

UltiTools, UltiToolsPlugin

public interface Localized

Localized interface.

Field Summary

Fields

Modifier and Type	Field	Description
static final String[]	LANGUAGE_EXTENSIONS	The language-file extensions a code may be declared by, matching UltiToolsPlugin's loader.

Method Summary

Modifier and Type	Method	Description
default String	i18n(String code, String str)	Returns a localized string for the given default text.
static boolean	isSafeLanguageCode(String code)	Checks code against the character allowlist languageCodeOf(String) documents: non-empty, starting with an ASCII letter or digit, every character thereafter an ASCII letter, digit, '_' or '-'.
static String	languageCodeOf(String fileName)	Returns fileName without its language extension, or null if it has none -- or if the remainder is not itself a plain language-code token.
static String	officialLanguageOf(String configured, List<String> officialCodes)	Resolves the official language a configured language name is based on (#608).
static List<String>	scanLangDirectory(File langDir)	Lists the immediate language-file children of langDir -- nested entries such as lang/extra/en.json are not descended into.
static List<String>	scanLangJar(File jarFile)	Enumerates jarFile's entries for immediate lang/* language children -- neither non-language entries (e.g.
static List<String>	scanLangResources(URL codeSourceLocation)	Enumerates the lang/* language resources at the given code-source location, handling both a packaged JAR and an exploded directory (development workspace) layout.
default List<String>	supported()	Get the language code of the plugin module.

Field Details

LANGUAGE_EXTENSIONS

static final String[] LANGUAGE_EXTENSIONS

The language-file extensions a code may be declared by, matching UltiToolsPlugin's loader.

.yml/.yaml were added in 6.3.0 (#389): eight of this ecosystem's modules ship YAML, and while only .json counted here they reported no supported languages at all, so resolveLanguageCode had nothing to consult.

Since:

6.3.0

Method Details

languageCodeOf

@Internal
static String languageCodeOf(String fileName)

Returns fileName without its language extension, or null if it has none -- or if the remainder is not itself a plain language-code token.

16-05 / CodeQL java/zipslip alert #11 (CWE-22). The returned value is not merely displayed: UltiToolsPlugin combines it directly into a File path (e.g. lang/<code>.json) with no other sanitisation, and this method is fed raw jar-entry names by scanLangJar(File) as well as raw on-disk filenames by scanLangDirectory(File). Before this fix, a jar entry named lang/..\..\evil.json (or the URL-decoded equivalent lang/../../evil.json) survived unchanged as the code ..\..\evil, which a downstream sink could then resolve outside the module's own lang/ directory.

The remainder is therefore also checked against a character allowlist -- [A-Za-z0-9][A-Za-z0-9_-]* -- before being accepted as a code at all: it must start with an ASCII letter or digit, and every character must be an ASCII letter, digit, '_' or '-'. This is deliberately a character allowlist, not a BCP-47 (or any other) language-tag grammar: every code this framework or any of its shipped modules actually uses (en, zh, en_US, zh-CN, ...) matches it, and no plausible language code needs a '.', '/', '\' or any other character this allowlist rejects. A candidate failing the allowlist returns null -- exactly the same "not a language file" outcome as a name with no recognised extension at all -- so a caller cannot tell "wrong extension" apart from "rejected as unsafe", by design: neither is a case a caller needs to react to differently.

Parameters:

fileName - a file or jar-entry name, without any directory part

Returns:

the language code, or null when the name is not a language file or its stripped remainder is not a safe language-code token

Since:

6.3.0

isSafeLanguageCode

@Internal
static boolean isSafeLanguageCode(String code)

Checks code against the character allowlist languageCodeOf(String) documents: non-empty, starting with an ASCII letter or digit, every character thereafter an ASCII letter, digit, '_' or '-'.

Exposed as public static for the same reason scanLangJar(File) and scanLangDirectory(File) are -- interface methods cannot be non-public before Java 9, so this is a direct test seam rather than API meant for module authors to call.

Parameters:

code - the candidate language code, already stripped of its extension

Returns:

whether code is safe to treat as a language code

Since:

6.3.0

officialLanguageOf

@Internal
static String officialLanguageOf(String configured,
 List<String> officialCodes)

Resolves the official language a configured language name is based on (#608).

Official language files are owned by the framework; an operator customises messages by copying an official file under a new name and selecting that name in plugins/UltiTools/config.yml (maintainer decision 2026-10-04). The new name starts with the official code it was copied from and a hyphen -- zh-myserver is based on zh -- and keys the custom file lacks come from that official file.

Returns configured itself when it is one of officialCodes; otherwise the longest official code c such that configured starts with c + "-", so zh-CN-myserver is based on zh-CN when both zh and zh-CN are official. Returns null when there is no such code, when configured is null, or when it fails isSafeLanguageCode(String) -- a name that could form a path outside a lang/ folder is never a custom language name. The caller chooses the fallback for null and says so in the log.

Parameters:

configured - the configured language value, possibly null

officialCodes - the official language codes the caller ships

Returns:

the official code configured is based on, or null if none

Since:

6.3.0

supported

default List<String> supported()

Get the language code of the plugin module. more Language code list
The returned list is derived from the lang/*.json, lang/*.yml and lang/*.yaml resources the implementor's own code source (its JAR, or an exploded directory in a development workspace) actually ships. An empty list means no language resources were found -- not that no language is supported. Overriding this method still wins over the derivation.

Gets the language codes a plugin supported.

Returns:

Supported language codes

Since:

6.3.0 derived from lang/*.json resources rather than @I18n (D-20)

See Also:

• Internationalization

scanLangResources

@Internal
static List<String> scanLangResources(URL codeSourceLocation)

Enumerates the lang/* language resources at the given code-source location, handling both a packaged JAR and an exploded directory (development workspace) layout. Reuses the getProtectionDomain().getCodeSource() -> JarFile idiom UltiToolsPlugin.saveResources() already uses, so this is correct on a module's first-ever startup, before its embedded resources have been extracted to disk. The location is resolved through CodeSourceLocations.toFile(URL), the same resolver the dictionary reader uses, so a module installed under a path with a space or a non-ASCII character still reports the languages it ships (#676 case 26).

Exposed as public static out of necessity, not invitation -- interface methods cannot be non-public before Java 9, so this is a direct test seam for supported()'s derivation rather than API meant for module authors to call.

Parameters:

codeSourceLocation - the URL returned by CodeSource.getLocation()

Returns:

the language codes found, sorted and de-duplicated; empty on any failure

scanLangDirectory

@Internal
static List<String> scanLangDirectory(File langDir)

Lists the immediate language-file children of langDir -- nested entries such as lang/extra/en.json are not descended into.

Parameters:

langDir - the lang/ directory to scan

Returns:

the language codes found; empty if langDir does not exist or is empty

scanLangJar

@Internal
static List<String> scanLangJar(File jarFile)

Enumerates jarFile's entries for immediate lang/* language children -- neither non-language entries (e.g. lang/README.txt) nor nested entries (e.g. lang/extra/en.json) are returned. No entry is extracted; this only reads names.

Parameters:

jarFile - the module's own JAR

Returns:

the language codes found; empty if jarFile cannot be opened as a JAR

i18n

default String i18n(String code,
 String str)

Returns a localized string for the given default text. The code parameter is not honoured by the framework's own implementation -- UltiToolsPlugin overrides this method final and resolves directly against the module's already-loaded Language, discarding code entirely. Language selection happens once at load time, via supported(), not per call. str is returned unchanged when it is absent as a key from that already-loaded dictionary.

Parameters:

code - language code -- not honoured by the framework's own i18n(String, String) override

str - default display text, also the dictionary lookup key

Returns:

a localized string, or str unchanged if the key is absent from the loaded dictionary

Since:

6.3.0 corrected wording -- see D-22 (#315)