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
| Language | Code | File Name | Language Field |
|---|---|---|---|
| Arabic | ar | ar.jsonc | Language.Arabic |
| Bulgarian | bg | bg.jsonc | Language.Bulgarian |
| Chinese (CN & TW) | zh-CN / zh-TW | zh-CN.jsonc / zh-TW.jsonc | Language.ChineseCN / Language.ChineseTW |
| Czech | cs | cs.jsonc | Language.Czech |
| Danish | da | da.jsonc | Language.Danish |
| Dutch | nl | nl.jsonc | Language.Dutch |
| English | en | en.jsonc | Language.English |
| Finnish | fi | fi.jsonc | Language.Finnish |
| French | fr | fr.jsonc | Language.French |
| German | de | de.jsonc | Language.German |
| Greek | el | el.jsonc | Language.Greek |
| Hungarian | hu | hu.jsonc | Language.Hungarian |
| Indonesian | id | id.jsonc | Language.Indonesian |
| Italian | it | it.jsonc | Language.Italian |
| Japanese | ja | ja.jsonc | Language.Japanese |
| Korean | ko | ko.jsonc | Language.Korean |
| Norwegian | no | no.jsonc | Language.Norwegian |
| Polish | pl | pl.jsonc | Language.Polish |
| Portuguese | pt | pt.jsonc | Language.Portuguese |
| Portuguese (Brazilian) | pt-BR | pt-BR.jsonc | Language.Brazilian |
| Romanian | ro | ro.jsonc | Language.Romanian |
| Russian | ru | ru.jsonc | Language.Russian |
| Spanish | es | es.jsonc | Language.Spanish |
| Spanish (Latin America) | es-419 | es-419.jsonc | Language.LatinAmerica |
| Swedish | sv | sv.jsonc | Language.Swedish |
| Thai | th | th.jsonc | Language.Thai |
| Turkish | tr | tr.jsonc | Language.Turkish |
| Ukrainian | uk | uk.jsonc | Language.Ukrainian |
| Vietnamese | vn | vn.jsonc | Language.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:
| Indexer | Returns | Description |
|---|---|---|
this[string key] | string | The translation stored under key. |
this[string key, params object[] args] | string | The 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);| Member | Callback Overload | Notes |
|---|---|---|
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.EnglishTwo 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.