-
Notifications
You must be signed in to change notification settings - Fork 23
Making a Plugin Multi Language Friendly
For most of Shine's existence, messages have always been hardcoded in English and sent from the server directly. In order to support multiple languages, the way you send notifications to players must be changed. Note that if you do not want or need to make a plugin multi-language friendly, you do not need to change anything. It is still possible to use the legacy hardcoded messaging systems.
Firstly, you'll need to make a new folder under locale/shine/extensions/pluginname, where pluginname is the name of your plugin. Inside this folder, should live a file named enGB.json containing the default English translations for your plugin. Other language translations will also need to live inside this folder, with their respective language names.
Next, you'll need to evaluate your plugin, and see what kind of messages it's sending. There are various ways to send translated messages to clients, which are outlined below.
If your plugin does not need to add any extra data to its messages, then these methods allow sending single translated phrases to clients.
Plugin:NotifyTranslated( Target, TranslationKey )
Similar to the existing Plugin:Notify(), this sends a translation key to the given client(s), and they then translate it into their local language. The translated value will be resolved from the plugin's translations, so make sure you have an entry for it.
Plugin:NotifyTranslatedError( Target, TranslationKey )
Similar to Shine:NotifyError(), this sends a standard error message to the target client(s) chat, but the message is translated using the given key.
Plugin:NotifyTranslatedCommandError( Target, TranslationKey )
Similar to Shine:NotifyCommandError(), this sends either an error message that is translated to the player's chat if they used a chat command, or to their console if they used the console.
In a lot of cases, the methods above are not enough to fully cover all the messages you need to send. You may need to add a player's name to a message, or a time value or some other dynamic data. This requires setting up a set of network messages for your translations, which should be done under the Plugin:SetupDataTable() event method.
Note that each Add<SomeMessageType> method has a complimentary Send<SomeMessageType> which should be used to send it. The sender method receives a target client (or table of clients, or nil to send to everyone), the registered translation key, and a table of values to send.
Plugin:AddTranslatedMessage( TranslationKey, Values )
Adds a network message that, when sent, will display a command notification against the given translation key and passed the given values for interpolation. This replaces Shine:CommandNotify(). For example:
-- Setup ACTION_PERFORMED translation key message, receives the PlayerName value.
function Plugin:SetupDataTable()
self:AddTranslatedMessage( "ACTION_PERFORMED", {
PlayerName = self:GetNameNetworkField()
} )
end
-- Assuming our translation string looks like this: "performed an action on {PlayerName}."
-- Then calling this on the server:
Plugin:SendTranslatedMessage( Client, "ACTION_PERFORMED", {
PlayerName = "Person8880"
} )
-- would display:
-- "SomeAdmin performed an action on Person8880."
-- assuming that Client represents the player named "SomeAdmin".Plugin:AddTranslatedNotify( TranslationKey, Values )
Adds a translated notification network message. This replaces Plugin:Notify(). Also, you must now place Plugin.NotifyPrefixColour in the shared.lua file rather than on the server, as the notification colour and message are built on the client-side. The prefix value is determined from the translation key NOTIFY_PREFIX. For example:
Plugin.NotifyPrefixColour = {
255, 255, 0
}
-- Setup ACTION_PERFORMED translation key message, receives the PlayerName value.
function Plugin:SetupDataTable()
self:AddTranslatedNotify( "ACTION_PERFORMED", {
PlayerName = self:GetNameNetworkField()
} )
end
-- Assuming our translation string looks like this: "{PlayerName} performed an action."
-- Then calling this on the server:
Plugin:SendTranslatedNotify( nil, "ACTION_PERFORMED", {
PlayerName = "Person8880"
} )
-- would display:
-- "[Plugin Prefix] Person8880 performed an action."
-- if "NOTIFY_PREFIX" is mapped to "[Plugin Prefix]".Plugin:AddTranslatedError( TranslationKey, Values )
Almost identical to Plugin:AddTranslatedNotify(), except it will display a standard error notification to the chat instead of a notification.
Plugin:AddTranslatedCommandError( TranslationKey, Values )
Essentially Plugin:NotifyTranslatedCommandError() but allowing data to be added to the message.
Plugin:AddTranslatedNotifyColour( TranslationKey, Values )
Adds a translated message to be displayed in a single colour. You must pass the colour through in your values table when you send the message, e.g.
Plugin:SendTranslatedNotifyColour( nil, "TRANSLATION_KEY", {
R = 255, G = 255, B = 0,
SomeOtherValue = "Cake"
} )If your plugin needs a lot of similar network messages, you can use the helper method Plugin:AddNetworkMessages().
Plugin:AddNetworkMessages( Type, MessageGroups )
For example:
function Plugin:SetupDataTable()
local MessageTypes = {
MessageType1 = {
SomeString = "string (32)"
},
MessageType2 = {
PlayerName = self:GetNameNetworkField()
}
}
-- Setup some command notifications.
self:AddNetworkMessages( "AddTranslatedMessage", {
-- Creates two translated messages, both having values MessageTypes.MessageType1, with keys "TRANSLATION_1" and "TRANSLATION_2".
[ MessageTypes.MessageType1 ] = {
"TRANSLATION_1", "TRANSLATION_2"
}
} )
-- Setup some plugin notifications too.
self:AddNetworkMessages( "AddTranslatedNotify", {
-- Same mapping behaviour as above. NOTIFY_1 and 2 have MessageTypes.MessageType1 as their values
-- and NOTIFY_3 and 4 have MessageTypes.MessageType2 as their values.
[ MessageTypes.MessageType1 ] = {
"NOTIFY_1", "NOTIFY_2"
},
[ MessageTypes.MessageType2 ] = {
"NOTIFY_3", "NOTIFY_4"
}
} )
end