discordgoi18n

README

discordgo-i18n

discordgo-i18n is a simple and lightweight Go package that helps you translate Go programs into languages supported by Discord.

• Built to ease usage of bwmarrin/discordgo
• Less verbose than go-i18n
• Supports multiple strings per key to make your bot "more alive"
• Supports strings with named variables using text/template syntax
• Supports message files of JSON format

Getting started

Installing

This assumes you already have a working Go environment, if not please see this page first.

go get will always pull the latest tagged release from the main branch.

go get github.com/kaysoro/discordgo-i18n

NOTICE: this package has been built to ease usage of bwmarrin/discordgo, it can be used for other projects but will be less practical.

Usage

Import the package into your project.

import i18n "github.com/kaysoro/discordgo-i18n"

Load bundles for locales to support.

err := i18n.LoadBundle(discordgo.French, "path/to/your/file.json")

The bundle format must respect the schema below; note text/template syntax is used to inject variables.
For a given key, value can be string, string array to randomize translations or even deep structures to group translations as wanted. In case any other type is provided, it is mapped to string automatically.

{
    "hello_world": "Hello world!",
    "hello_anyone": "Hello {{ .anyone }}!",
    "image": "https://media2.giphy.com/media/Ju7l5y9osyymQ/giphy.gif",
    "bye": ["See you", "Bye!"],
    "command": {
        "scream": {
            "name": "scream",
            "description": "Screams something",
            "dog": "Waf waf! 🐶",
            "cat": "Miaw! 🐱"
        }
    }
}

By default, the locale fallback used when a key does not have any translations is discordgo.EnglishUS. To change it, use the following method.

i18n.SetDefault(discordgo.ChineseCN)

To get translations use the below thread-safe method; if any translation cannot be found or an error occurred even with the fallback, key is returned.

helloWorld := i18n.Get(discordgo.EnglishUS, "hello_world")
fmt.Println(helloWorld)
// Prints "Hello world!"

helloAnyone := i18n.Get(discordgo.EnglishUS, "hello_anyone")
fmt.Println(helloAnyone)
// Prints "Hello {{ .anyone }}!"

helloAnyone = i18n.Get(discordgo.EnglishUS, "hello_anyone", i18n.Vars{"anyone": "Nick"})
fmt.Println(helloAnyone)
// Prints "Hello Nick!"

bye := i18n.Get(discordgo.EnglishUS, "bye")
fmt.Println(bye)
// Prints randomly "See you" or "Bye!"

keyDoesNotExist := i18n.Get(discordgo.EnglishUS, "key_does_not_exist")
fmt.Println(keyDoesNotExist)
// Prints "key_does_not_exist"

dog := i18n.Get(discordgo.EnglishUS, "command.scream.dog")
fmt.Println(dog)
// Prints "Waf waf! 🐶"

To get localizations for a command name, description, options or other fields, use the below thread-safe method. It retrieves a *map[discordgo.Locale]string based on the loaded bundles.

screamCommand := discordgo.ApplicationCommand{
    Name:                     "scream",
    Description:              "Here a default description for my command",
    NameLocalizations:        i18n.GetLocalizations("command.scream.name"),
    DescriptionLocalizations: i18n.GetLocalizations("command.scream.description"),
}

Here an example of how it can work with interactions.

func HelloWorld(s *discordgo.Session, i *discordgo.InteractionCreate) {

    err := s.InteractionRespond(i.Interaction, &discordgo.InteractionResponse{
		Type: discordgo.InteractionResponseChannelMessageWithSource,
		Data: &discordgo.InteractionResponseData{
			Embeds: []*discordgo.MessageEmbed{
                {
                    Title:       i18n.Get(i.Locale, "hello_world"),
                    Description: i18n.Get(i.Locale, "hello_anyone", i18n.Vars{"anyone": i.Member.Nick}),
                    Image:       &discordgo.MessageEmbedImage{URL: i18n.Get(i.Locale, "image")},
                },
            },
		},
	})

    // ...
}

Contributing

Contributions are very welcomed, however please follow the below guidelines.

• First open an issue describing the bug or enhancement so it can be discussed.
• Try to match current naming conventions as closely as possible.
• Create a Pull Request with your changes against the main branch.

Licence

discordgo-i18n is available under the MIT license. See the LICENSE file for more info.

Documentation

Index

• func Get(language discordgo.Locale, key string, values ...Vars) string
• func GetLocalizations(key string, values ...Vars) *map[discordgo.Locale]string
• func LoadBundle(language discordgo.Locale, file string) error
• func SetDefault(language discordgo.Locale)
• type Vars

Functions

func Get

func Get(language discordgo.Locale, key string, values ...Vars) string

Get gets a translation corresponding to a locale and a key. Optional Vars parameter is used to inject variables in the translation. When a key does not match any translations in the desired locale, the default locale is used instead. If the situation persists with the fallback, key is returned. If more than one translation is available for dedicated key, it is picked randomly. Thread-safe.

func GetLocalizations

func GetLocalizations(key string, values ...Vars) *map[discordgo.Locale]string

GetLocalizations retrieves translations from every loaded bundles. Aims to simplify discordgo.ApplicationCommand instanciations by providing localizations structures that can be used for any localizable field (example: command name, description, etc). Thread-safe.

func LoadBundle

func LoadBundle(language discordgo.Locale, file string) error

LoadBundle loads a translation file corresponding to a specified locale. Not thread-safe; designed to be called during initialization.

func SetDefault

func SetDefault(language discordgo.Locale)

SetDefaults sets the locale used as a fallback. Not thread-safe; designed to be called during initialization.

Types

type Vars

type Vars map[string]interface{}

Vars is the collection used to inject variables during translation. This type only exists to be less verbose.