swiftlys2/docs/api/releases/features/ai/

Translations

SwiftlyS2's translation APIs localize plugin text by key and automatically resolve player-specific language.

Text is read either from APIISwiftlyCore.Localizer (Core.Localizer, an APIILocalizer) for server-wide lookups, or from APIISwiftlyCore.Translation (Core.Translation, an APIITranslationService) when the text depends on the receiving player.

Translation File Layout

Place .jsonc files named by language code under resources/translations/ (for example en.jsonc, fr.jsonc, pt-BR.jsonc, es-419.jsonc). At least one must exist for the plugin's translations to load.

Custom language codes work for direct lookups through Core.Localizer, but Core.Translation.GetPlayerLocalizer(player) only resolves the codes listed below.

Keep an en.jsonc baseline with all keys so unsupported or incomplete languages still have usable text.

Language Codes

LanguageCodeFile NameLanguage Field
Arabicarar.jsoncLanguage.Arabic
Bulgarianbgbg.jsoncLanguage.Bulgarian
Chinese (CN & TW)zh-CN / zh-TWzh-CN.jsonc / zh-TW.jsoncLanguage.ChineseCN / Language.ChineseTW
Czechcscs.jsoncLanguage.Czech
Danishdada.jsoncLanguage.Danish
Dutchnlnl.jsoncLanguage.Dutch
Englishenen.jsoncLanguage.English
Finnishfifi.jsoncLanguage.Finnish
Frenchfrfr.jsoncLanguage.French
Germandede.jsoncLanguage.German
Greekelel.jsoncLanguage.Greek
Hungarianhuhu.jsoncLanguage.Hungarian
Indonesianidid.jsoncLanguage.Indonesian
Italianitit.jsoncLanguage.Italian
Japanesejaja.jsoncLanguage.Japanese
Koreankoko.jsoncLanguage.Korean
Norwegiannono.jsoncLanguage.Norwegian
Polishplpl.jsoncLanguage.Polish
Portugueseptpt.jsoncLanguage.Portuguese
Portuguese (Brazilian)pt-BRpt-BR.jsoncLanguage.Brazilian
Romanianroro.jsoncLanguage.Romanian
Russianruru.jsoncLanguage.Russian
Spanisheses.jsoncLanguage.Spanish
Spanish (Latin America)es-419es-419.jsoncLanguage.LatinAmerica
Swedishsvsv.jsoncLanguage.Swedish
Thaithth.jsoncLanguage.Thai
Turkishtrtr.jsoncLanguage.Turkish
Ukrainianukuk.jsoncLanguage.Ukrainian
Vietnamesevnvn.jsoncLanguage.Vietnamese

Example Translation File

{
    // General
    "plugin.name": "My Plugin",
    "plugin.ready": "Plugin is ready.",
 
    // Command feedback
    "command.heal.success": "You have been healed.",
    "command.heal.other": "{0} healed {1}",
    "command.heal.no_permission": "You do not have permission.",
 
    // Errors
    "error.player_not_found": "Player '{0}' was not found."
}

Translation values are plain strings, so chat color codes such as [red] or [green] can be written directly inside them and are applied when the text is sent. See Chat & CenterHTML Styling for the full color list.

Server-Side Localization

APIILocalizer is a read-only accessor for messages that aren't player-specific. It has no methods, only two indexers:

IndexerReturnsDescription
this[string key]stringThe translation stored under key.
this[string key, params object[] args]stringThe translation stored under key, formatted with args.

The overload taking args formats the translation with string.Format(string, object[]), so {0}, {1}, ... placeholders and standard format specifiers work exactly as they do elsewhere in .NET - keep placeholder order stable across languages:

string readyMessage = Core.Localizer["plugin.ready"];
string versionMessage = Core.Localizer["plugin.version", "1.2.0"];
string scoreMessage = Core.Localizer["plugin.score", player.Name, 1500, 0.75];

Core.Localizer is the APIISwiftlyCore.Localizer property, and an injected ILocalizer resolves to the same instance.

Missing Keys and Fallback

Lookup is all the API exposes. Both indexers return a non-nullable string and there is no TryGet-style variant, and neither APIILocalizer nor APIITranslationService lets a plugin see which language a lookup resolved to or configure a fallback order. A key missing from the active language file therefore can't be detected through the localizer, so keep the same key set in every file - and take the resolved language from the player when you need it (player.PlayerLanguage, see The Language Type).

Player-Specific Localization

APIITranslationService exposes a single member: APIITranslationService.GetPlayerLocalizer takes an APIIPlayer and returns the APIILocalizer for that player, with the same two indexers as above. Use it when the output should match the player's language:

public async Task GreetAsync(IPlayer player)
{
    var localizer = Core.Translation.GetPlayerLocalizer(player);
    string message = localizer["welcome.message", player.Name];
 
    await player.SendChatAsync(message);
}

GetPlayerLocalizer only returns a localizer - sending the text is up to you. The player-facing send methods on APIIPlayer (SendChat/SendChatAsync, SendCenter/SendCenterAsync, SendChatEOT/SendChatEOTAsync, SendAlert/SendAlertAsync, SendNotify/SendNotifyAsync, SendConsole/SendConsoleAsync and SendCenterHTML/SendCenterHTMLAsync) all take the finished string.

Broadcasting in Each Player's Language

APIIPlayerManagerService.SendMessage and APIIPlayerManagerService.SendMessageAsync also have overloads taking a APIMessageType plus a Func<IPlayer, ILocalizer, string> callback instead of a fixed string. The callback receives the recipient and their localizer, so a single call builds the message per player in that player's own language:

Core.PlayerManager.SendMessageAsync(MessageType.Chat, (player, localizer) =>
    localizer["plugin.welcome", player.Name]);
 
// the CenterHTML variants also take the display duration in milliseconds
Core.PlayerManager.SendMessageAsync(MessageType.CenterHTML, (player, localizer) =>
    localizer["plugin.countdown", 30], htmlDuration: 3000);
MemberCallback OverloadNotes
SendMessage(MessageType kind, Func<IPlayer, ILocalizer, string> messageCallback)[ThreadUnsafe]
SendMessage(MessageType kind, Func<IPlayer, ILocalizer, string> messageCallback, int htmlDuration = 5000)[ThreadUnsafe]
SendMessageAsync(MessageType kind, Func<IPlayer, ILocalizer, string> messageCallback)Returns Task
SendMessageAsync(MessageType kind, Func<IPlayer, ILocalizer, string> messageCallback, int htmlDuration = 5000)Returns Task

Off the game thread, use the Async variants (or Core.Scheduler) - see Thread Safety.

The Language Type

APILanguage is a sealed class wrapping a language code. APIIPlayer.PlayerLanguage returns one, which is handy for diagnostics or conditional flows:

if (player.PlayerLanguage.Equals(Language.German))
{
    Core.Logger.LogInformation("German client: {SteamId}", player.SteamID);
}

APILanguage does not overload ==, so player.PlayerLanguage == Language.German compares references and only matches the very same instance. Use Equals, or compare Value, for value comparison.

Value is the code and ToString() returns it. The type converts implicitly to string, but not the other way round - building one from a code string takes the constructor:

string fromValue = player.PlayerLanguage.Value;
string fromConversion = player.PlayerLanguage;
 
var custom = new Language("en"); // equal to Language.English

Two APILanguage instances are equal when their codes are equal: the type implements IEquatable<Language>, and GetHashCode is derived from the code, so a APILanguage works as a dictionary key or in a set. The static fields in the Language Codes table cover the codes listed there; since the constructor is public, new Language("en") builds a value equal to Language.English.

services.AddSwiftly(Core) registers Core.Localizer and Core.Translation as singletons, so ILocalizer and ITranslationService can be constructor-injected - see Dependency Injection.

Key Design Best Practices

  • Use stable dot-separated keys (for example command.heal.success).
  • Keep the same key set across all language files.
  • Add JSONC comments for translator context when placeholders are involved.
  • Avoid string concatenation in code for translatable sentences.