stefandevai/i18n_keyval

Easy to use and customizable C++ internationalization library.

i18n_keyval

Easy to use and customizable internationalization library. The core library has no external dependencies. You can, however, use a custom translator to provide translated strings using xml, json, lua or any other method you want using an external library. Custom translators for some known libraries are already provided.

Usage

Default translator

You need to provide a i18n::translations object containing all your locales with their respective localized strings.

Example:

#include <i18n_keyval/i18n.hpp>
#include <i18n_keyval/translators/basic.hpp>

using namespace i18n::literals;

i18n::translations translations{
  {"en", {{"moon", "Moon"}, {"sun", "Sun"}}},
  {"es", {{"moon", "Luna"}, {"sun", "Sol"}}},
};

i18n::initialize_translator(translations);

i18n::set_locale("en");
std::cout << "moon"_t << '\n';
std::cout << "sun"_t << '\n';

i18n::set_locale("es");
std::cout << i18n::t("moon") << '\n';
std::cout << i18n::t("sun") << '\n';

Output:

Moon
Sun
Luna
Sol

nlohmann/json translator

Built-in nlohmann/json translator. You need to set up the library by yourself.

Example:

// translations/en/translation.json
{
    "moon": "Moon",
    "animals": {
        "cat": "Cat"
    }
}

// translations/es/translation.json
{
    "moon": "Luna",
    "animals": {
        "cat": "Gato"
    }
}

#include <i18n_keyval/i18n.hpp>
#include <i18n_keyval/translators/nlohmann_json.hpp>

using namespace i18n::literals;

i18n::initialize_translator<i18n::translators::nlohmann_json>();

// Or provide a custom directory where the translator can find the locales
// i18n::initialize_translator<i18n::translators::nlohmann_json>("data/translations");

i18n::set_locale("en");
std::cout << "moon"_t << '\n';
std::cout << "animals.cat"_t << '\n';

i18n::set_locale("es");
std::cout << i18n::t("moon") << '\n';
std::cout << i18n::t("animals.cat") << '\n';

Output:

Moon
Cat
Luna
Gato

Custom translator

To use a custom translator, you have to provide any class that implements a set_locale and translate methods. This allows you to retrieve strings with other methods such as xml, lua, other json library or a custom container.

Example:

#include <i18n_keyval/i18n.hpp>

using namespace i18n::literals;

struct translator
{
  std::string locale{};
  std::unordered_map<std::string, std::string> en_translations{{ "moon", "Moon" }};
  std::unordered_map<std::string, std::string> es_translations{{ "moon", "Luna" }};

  void set_locale(const std::string& locale)
  {
    this->locale = locale;
  }

  std::string translate(const char* key, const std::size_t length) const
  {
    if (locale == "en")
    {
      return en_translations.at(std::string(key));
    }
    else if (locale == "es")
    {
      return es_translations.at(std::string(key));
    }

    return std::string(key);
  }
};

i18n::initialize_translator<translator>();

i18n::set_locale("en");
std::cout << "moon"_t << '\n';

i18n::set_locale("es");
std::cout << i18n::t("moon") << '\n';

Output:

Moon
Luna

Features

• String literal usage
• Free function usage
• Nested json
• Plurals
• Plural interpolation

Translators

• Default (using unordered_map)
• nlohman/json (json)
• rapidjson (json)
• sol2 (lua)
• pugixml (xml)
• tinyxml2 (xml)