Context aware i18n with a short and consise API, pluralization, interpolation, and `fs.FS` support. YAML locale definitions are based on [Rails i18n](https://guides.rubyonrails.org/i18n.html)

# ctxi18n

[![Lint](https://github.com/invopop/ctxi18n/actions/workflows/lint.yaml/badge.svg)](https://github.com/invopop/ctxi18n/actions/workflows/lint.yaml)
[![Test Go](https://github.com/invopop/ctxi18n/actions/workflows/test.yaml/badge.svg)](https://github.com/invopop/ctxi18n/actions/workflows/test.yaml)
[![Go Report Card](https://goreportcard.com/badge/github.com/invopop/ctxi18n)](https://goreportcard.com/report/github.com/invopop/ctxi18n)
[![codecov](https://codecov.io/gh/invopop/ctxi18n/graph/badge.svg?token=17H4KY3CNZ)](https://codecov.io/gh/invopop/ctxi18n)
[![GoDoc](https://godoc.org/github.com/invopop/ctxi18n?status.svg)](https://godoc.org/github.com/invopop/ctxi18n)
![Latest Tag](https://img.shields.io/github/v/tag/invopop/ctxi18n)

Go Context Internationalization - translating apps easily.

## Introduction

`ctxi18n` is heavily influenced by [internationalization in Ruby on Rails](https://guides.rubyonrails.org/i18n.html) and aims to make it just as straightforward in Go applications.

As the name suggests, `ctxi18n` focusses on making i18n data available inside an application's context instances, but is sufficiently flexible to used directly if needed.

Key Features:

- Loads locale files written in YAML or JSON with a similar structure those in Ruby i18n.
- Makes it easy to add a locale object to the context.
- Supports `fs.FS` to load data.
- Short method names like `i18n.T()` or `i18n.N()`.
- Support for simple interpolation using keys, e.g. `Some %{key} text`
- Support for pluralization rules.
- Default values when translations are missing.

## Usage

Import the library with:

```go
import "github.com/invopop/ctxi18n"
```

First you'll need to load YAML or JSON translation definitions. Files may be named and structured however you like, but the contents must always follow the same pattern of language and properties, for example:

```yaml
en:
  welcome:
    title: "Welcome to our application!"
    login: "Log in"
    signup: "Sign up"
    forgot-password: "Forgot Password?"
es:
  welcome:
    title: "¡Bienvenido a nuestra aplicación!"
    login: "Ingresarse"
    signup: "Registrarse"
    forgot-password: "¿Olvidaste tu contraseña?
```

The first level of properties of the object **must** always define the locale that the rest of sub-object's contents will provide translations for.

Files will all be deep-merged on top of each other so you can safely extend dictionaries from multiple sources.

To load the dictionary run something like the following where the `asset.Content` is a package containing [embedded files](https://pkg.go.dev/embed):

```go
if err := ctxi18n.Load(assets.Content); err != nil {
    panic(err)
}
```

If you'd like to set a default base language to try to use for any missing translations, load the assets with a default:

```go
if err := ctxi18n.LoadWithDefault(assets.Content, "en"); err != nil {
    panic(err)
}
```

You'll now have a global set of locales prepared in memory and ready to use. Assuming your application uses some kind of context such as from an HTTP or gRPC request, you'll want to add a single locale to it:

```go
ctx = ctxi18n.WithLocale(ctx, "en")
```

Locale selection is performed according to [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html) and the `Accept-Language` header, so you can pass in a code string and an attempt will be made to find the best match:

```go
ctx = ctxi18n.WithLocale(ctx, "en-US,en;q=0.9,es;q=0.8")
```

In this example, the first locale to matched will be `en-US`, followed by just `en`, then `es`:

Getting translations is straightforward, you have two options:

1.  call methods defined in the package with the context, or,
2.  extract the locale from the context and use.

To translate without extracting the locale, you'll need to load the `i18n` package which contains all the structures and methods used by the main `ctxi18n` without any globals:

```go
import "github.com/invopop/ctxi18n/i18n"
```

Then use it with the context:

```go
fmt.Println(i18n.T(ctx, "welcome.title"))
```

Notice in the example that `title` was previously defined inside the `welcome` object in the source YAML, and we're accessing it here by defining the path `welcome.title`.

To use the `Locale` object directly, extract it from the context and call the methods:

```go
l := ctxi18n.Locale(ctx)
fmt.Println(l.T("welcome.title"))
```

There is no preferred way on how to use this library, so please use whatever best first your application and coding style. Sometimes it makes sense to pass in the context in every call, other times the code can be shorter and more concise by extracting it.

### Defaults

If a translation is missing from the locale a "missing" text will be produced, for example:

```go
fmt.Println(l.T("welcome.no.text"))
```

Will return a text that follows the `fmt.Sprintf` missing convention:

```
!(MISSING welcome.no.text)
```

This can be useful for translators to figure out which texts are missing, but sometimes a default value is more appropriate:

```go
fmt.Println(i18n.T(ctx, "welcome.question", i18n.Default("Just ask!")))
// output: "Just ask!"
code := "EUR"
fmt.Println(i18n.T(ctx, "currencies."+code, i18n.Default(code)))
// output: "EUR"
```

An alternative to using defaults is to check if the key exists using the `Has` method:

```go
if !i18n.Has(ctx, "welcome.question") {
  fmt.Println("Just ask!")
}
```

### Interpolation

Go's default approach for interpolation using the `fmt.Sprintf` and related methods is good for simple use-cases. For example, given the following translation:

```yaml
en:
  welcome:
    title: "Hi %s, welcome to our App!"
```

You can get the translated text and interpolate with:

```go
i18n.T(ctx, "welcome.title", "Sam")
```

This however is an _anti-pattern_ when it comes to translating applications as translators may need to change the order of replaced words. To get around this, `ctxi18n` supports simple named interpolation as follows:

```yaml
en:
  welcome:
    title: "Hi %{name}, welcome to our App!"
```

```go
i18n.T(ctx, "welcome.title", i18n.M{"name":"Sam"})
```

The `i18n.M` map is used to perform a simple find and replace on the matching translation. The `fmt.Sprint` method is used to convert values into strings, so you don't need to worry about simple serialization like for numbers.

Interpolation can also be used alongside default values:

```go
i18n.T(ctx, "welcome.title", i18n.Default("Hi %{name}"), i18n.M{"name":"Sam"})
```

## Pluralization

When texts include references to numbers we need internationalization libraries like `ctxi18n` that help define multiple possible translations according to a number. Pluralized translations are defined like this:

```yaml
en:
  inbox:
    emails:
      zero: "You have no emails."
      one: "You have %{count} email."
      other: "You have %{count} emails.
```

The `inbox.emails` tag has a sub-object that defines all the translations we need according to the pluralization rules of the language. In the case of English which uses the default rule set, `zero` is an optional definition that will be used if provided and fallback on `other` if not.

To use these translations, call the `i18n.N` method:

```go
count := 2
fmt.Println(i18n.N(ctx, "inbox.emails", count, i18n.M{"count": count}))
```

The output from this will be: "You have 2 emails."

In the current implementation of `ctxi18n` there are very few pluralization rules defined, please submit PRs if your language is not covered!

## Scopes

As your application gets more complex, it can get repetitive having to use the same base keys. To get around this, use the `WithScope` helper method inside a context:

```go
ctx := i18n.WithScope(ctx, "welcome")
i18n.T(ctx, ".title", i18n.M{"name":"Sam"})
```

Anything with the `.` at the beginning will append the scope. You can continue to use any other key in the locale by not using the `.` at the front.

## Templ

[Templ](https://templ.guide/) is a templating library that helps you create components that render fragments of HTML and compose them to create screens, pages, documents or apps.

The following "Hello World" example is taken from the [Templ Guide](https://templ.guide) and shows how you can quickly add translations the leverage the built-in `ctx` variable provided by Templ.

```yaml
en:
  welcome:
    hello: "Hello, %{name}"
```

```go
package main

import "github.com/invopop/ctxi18n/i18n"

templ Hello(name string) {
  <span class="hello">
    { i18n.T(ctx, "welcome.hello", i18n.M{"name": name}) }
  </span>
}

templ Greeting(person Person) {
  <div class="greeting">
    @Hello(person.Name)
  </div>
}
```

To save even more typing, it might be worth defining your own templ wrappers around those defined in the `i18n` package. Check out the [gobl.html `t` package](https://github.com/invopop/gobl.html/tree/main/components/t) for an example.

# Examples

The following is a list of Open Source projects using this library from which you can see working examples for your own solutions. Please send in a PR if you'd like to add your project!

- [GOBL HTML](https://github.com/invopop/gobl.html) - generate HTML files like invoices from [GOBL](https://gobl.org) documents.


ctxi18n

CGo bindings to Yandex.Mystem - russian morphology analyzer

# go-mystem [![Build Status](https://travis-ci.org/dveselov/mystem.svg?branch=master)](https://travis-ci.org/dveselov/mystem) [![GoDoc](https://godoc.org/github.com/dveselov/mystem?status.svg)](https://godoc.org/github.com/dveselov/mystem) [![Go Report Card](https://goreportcard.com/badge/github.com/dveselov/go-mystem)](https://goreportcard.com/report/github.com/dveselov/mystem) [![Coverage Status](https://coveralls.io/repos/github/dveselov/go-mystem/badge.svg)](https://coveralls.io/github/dveselov/go-mystem)
CGo bindings to Yandex.Mystem - russian morphology analyzer.

# Install
```bash
$ wget https://github.com/yandex/tomita-parser/releases/download/v1.0/libmystem_c_binding.so.linux_x64.zip
$ unzip libmystem_c_binding.so.linux_x64.zip
$ sudo cp libmystem_c_binding.so /usr/lib/
$ sudo ln -s /usr/lib/libmystem_c_binding.so /usr/lib/libmystem_c_binding.so.1
$ go get -u github.com/dveselov/mystem
```

# Usage
```go
package main

import (
    "fmt"
)

import "github.com/dveselov/mystem"

func main() {
    analyses := mystem.NewAnalyses("маша")
    defer analyses.Close()
    fmt.Println(fmt.Sprintf("Analyze of '%s':", "маша"))
    for i := 0; i < analyses.Count(); i++ {
        lemma := analyses.GetLemma(i)
        grammemes := lemma.StemGram()
        fmt.Println(fmt.Sprintf("%d. %s - %v", i+1, lemma.Text(), grammemes))
    }
}
```
Output'll looks like this:
```
Analyze of 'маша':
1. маша - [136 155 191 201]
2. махать - [137 196 206]
```

# License

Source code of `go-mystem` is licensed under MIT license, but Yandex.Mystem have their own [EULA](https://yandex.ru/legal/mystem/) (allows commercial use), that you must accept.


go-mystem

go-pinyin
=========

[![Build Status](https://github.com/mozillazg/go-pinyin/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/mozillazg/go-pinyin/actions/workflows/ci.yml)
[![Coverage Status](https://coveralls.io/repos/mozillazg/go-pinyin/badge.svg?branch=master)](https://coveralls.io/r/mozillazg/go-pinyin?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/mozillazg/go-pinyin)](https://goreportcard.com/report/github.com/mozillazg/go-pinyin)
[![GoDoc](https://godoc.org/github.com/mozillazg/go-pinyin?status.svg)](https://godoc.org/github.com/mozillazg/go-pinyin)

汉语拼音转换工具 Go 版。


Installation
------------

```
go get github.com/mozillazg/go-pinyin
```

install CLI tool:

```
# go version>=1.17
go install github.com/mozillazg/go-pinyin/cli/pinyin@latest

# go version<1.17
go get -u github.com/mozillazg/go-pinyin/cli/pinyin

$ pinyin 中国人
zhōng guó rén
```


Documentation
--------------

API documentation can be found here:
https://godoc.org/github.com/mozillazg/go-pinyin


Usage
------

```go
package main

import (
	"fmt"
	"github.com/mozillazg/go-pinyin"
)

func main() {
	hans := "中国人"

	// 默认
	a := pinyin.NewArgs()
	fmt.Println(pinyin.Pinyin(hans, a))
	// [[zhong] [guo] [ren]]

	// 包含声调
	a.Style = pinyin.Tone
	fmt.Println(pinyin.Pinyin(hans, a))
	// [[zhōng] [guó] [rén]]

	// 声调用数字表示
	a.Style = pinyin.Tone2
	fmt.Println(pinyin.Pinyin(hans, a))
	// [[zho1ng] [guo2] [re2n]]

	// 开启多音字模式
	a = pinyin.NewArgs()
	a.Heteronym = true
	fmt.Println(pinyin.Pinyin(hans, a))
	// [[zhong] [guo] [ren]]
	a.Style = pinyin.Tone2
	fmt.Println(pinyin.Pinyin(hans, a))
	// [[zho1ng zho4ng] [guo2] [re2n]]

	fmt.Println(pinyin.LazyPinyin(hans, pinyin.NewArgs()))
	// [zhong guo ren]

	fmt.Println(pinyin.Convert(hans, nil))
	// [[zhong] [guo] [ren]]

	fmt.Println(pinyin.LazyConvert(hans, nil))
	// [zhong guo ren]
}
```

注意：

* 默认情况下会忽略没有拼音的字符（可以通过自定义 `Fallback` 参数的值来自定义如何处理没有拼音的字符，
  详见 [示例](https://godoc.org/github.com/mozillazg/go-pinyin#example-Pinyin--FallbackCustom1)）。
* 根据 [《汉语拼音方案》](http://www.moe.gov.cn/s78/A19/yxs_left/moe_810/s230/195802/t19580201_186000.html) y，w，ü (yu) 都不是声母，
  以及不是所有拼音都有声母，如果这不是你预期的话，你可能需要的是首字母风格 `FirstLetter`
  （ [详细信息](https://github.com/mozillazg/python-pinyin#%E4%B8%BA%E4%BB%80%E4%B9%88%E6%B2%A1%E6%9C%89-y-w-yu-%E5%87%A0%E4%B8%AA%E5%A3%B0%E6%AF%8D) ）。


Related Projects
-----------------

* [hotoo/pinyin](https://github.com/hotoo/pinyin): 汉语拼音转换工具 Node.js/JavaScript 版。
* [mozillazg/python-pinyin](https://github.com/mozillazg/python-pinyin): 汉语拼音转换工具 Python 版。
* [mozillazg/rust-pinyin](https://github.com/mozillazg/rust-pinyin): 汉语拼音转换工具 Rust 版。


pinyin data
-----------------

* 使用 [pinyin-data](https://github.com/mozillazg/pinyin-data) 的拼音数据


License
---------

Under the MIT License.


go-pinyin

Another i18n pkg for golang, which follows GNU gettext style and supports .po/.mo files: `t.T (gettext)`, `t.N (ngettext)`, etc. And it contains a cmd tool [xtemplate](https://github.com/youthlin/t/blob/main/cmd/xtemplate), which can extract messages as a pot file from text/html template

# t
t: a translation util for go, inspired by GNU gettext  
t: GNU gettext 的 Go 语言实现，Go 程序的国际化工具  
[![sync-to-gitee](https://github.com/youthlin/t/actions/workflows/gitee.yaml/badge.svg)](https://github.com/youthlin/t/actions/workflows/gitee.yaml)
[![test](https://github.com/youthlin/t/actions/workflows/test.yaml/badge.svg)](https://github.com/youthlin/t/actions/workflows/test.yaml)
[![codecov](https://codecov.io/gh/youthlin/t/branch/main/graph/badge.svg?token=6RyU5nb3YT)](https://codecov.io/gh/youthlin/t)
[![Go Report Card](https://goreportcard.com/badge/github.com/youthlin/t)](https://goreportcard.com/report/github.com/youthlin/t)
[![Go Reference](https://pkg.go.dev/badge/github.com/youthlin/t.svg)](https://pkg.go.dev/github.com/youthlin/t)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fyouthlin%2Ft.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fyouthlin%2Ft?ref=badge_shield)


## Install 安装

```bash
go get -u github.com/youthlin/t
```

go.mod
```go
require (
    github.com/youthlin/t latest
)
```

Gitee 镜像：[gitee.com/youthlin/gottext](gitee.com/youthlin/gottext) (gottext: go + gettext)
> 鸣谢仓库同步工具：https://github.com/Yikun/hub-mirror-action
```
// 使用 gitee 镜像
// go.mod:
replace github.com/youthlin/t latest => gitee.com/youthlin/gottext latest
```


## Usage 使用
```go
path := "path/to/filename.po" // .po, .mo file
path = "path/to/po_mo/dir"    // or dir.
// (mo po 同名的话，po 后加载，会覆盖 mo 文件，因为 po 是文本文件，方便修改生效)
// 1 bind domain 绑定翻译文件
t.Load(path) // 默认绑定在 default 域 会自动搜索路径下的文件，读取 po/mo 里的语言标签进行注册
t.Bind("my-domain", path) // 或者指定Ø文本域
// 2 set current domain 设置使用的文本域
t.SetDomain("my-domain")
// 3 set user language 设置用户语言
// t.SetLocale("zh_CN")
t.SetLocale(t.MostMatchLocale()) // empty to use system default
// 4 use the gettext api 使用 gettext 翻译接口
fmt.Println(t.T("Hello, world"))
fmt.Println(t.T("Hello, %v", "Tom"))
fmt.Println(t.N("One apple", "%d apples", 1)) // One apple
fmt.Println(t.N("One apple", "%d apples", 2)) // %d apples
// t.N(single, plural, n, args...)
// n => used to choose single or plural
// args => to format
// args... supported, used to format string
// 支持传入 args... 参数用于格式化输出
fmt.Println(t.N("One apple", "%d apples", 2, 2)) // 2 apples
fmt.Println(t.N("%[2]s has one apple", "%[2]s has %[1]d apples", 2, 200, "Bob"))
// Bob has 200 apples
t.X("msg_context_text", "msg_id")
t.X("msg_context_text", "msg_id")
t.XN("msg_context_text", "msg_id", "msg_plural", n)
```

## API
```go
T(msgID, args...)
N(msgID, msgIDPlural, n, args...) // and N64
X(msgCTxt, msgID, args...)
XN(msgCTxt, msgID, msgIDPlural, n, args...) // and XN64
D(domain)
L(locale)
// T:  gettext
// N:  ngettext
// X:  pgettext
// XN: npgettext
// D:  with domain
// L:  with locale(language)
```

## Domain 文本域
```go
t.Bind(domain1, path1)
t.Bind(domain2, path2)
t.SetLocale("zh_CN")

t.T("msg_id")           // use default domain

t.SetDomain(domain1)
t.T("msg_id")            // use domain1
t.D(domain2).T("msg_id") // use domain2
t.D("unknown-domain").T("msg_id") // return "msg_id" directly

```

## Language 指定语言
If you are building a web application, you may want each request use diffenrent language, the code below may help you:  
如果你写的是 web 应用而不是 cli 工具，你可能想让每个 request 使用不同的语言，请看：

```go
t.Load(path)

// a) Specify a language 可以指定语言
t.L("zh_CN").T("msg_id")

// b) every one use his own language 每个用户使用他接受的语言
// b.1) server supports 第一步，服务器支持的语言
langs := t.Locales()
// golang.org/x/text/language
// EN: https://blog.golang.org/matchlang
// 中文: https://learnku.com/docs/go-blog/matchlang/6525
var supported []language.Tag
for _, lang =range langs{
    supported = append(supported, language.Make(lang))
}
matcher := language.NewMatcher(supported)
// b.2) user accept 第二步，用户接受的语言
// Judging by the browser header（Accept-Language）
// 根据浏览器标头获取用户语言
// or: userAccept := []language.Tag{ language.Make("lang-code-from-cookie") }
// 或从 cookie 中获取用户语言偏好
userAccept, q, err :=language.ParseAcceptLanguage("zh-CN,zh;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6")
// b.3) match 第三步，匹配出最合适的
matchedTag, index, confidence := matcher.Match(userAccept...)
// confidence may language.No, language.Low, language.High, language.Exact
// 这里 confidence 是指匹配度，可以根据你的实际需求决定是否使用匹配的语言。
// 如服务器支持 英文、简体中文，如果用户是繁体中文，那匹配度就不是 Exact，
// 这时根据实际需求决定是使用英文，还是简体中文。
userLang := langs[index]
t.L(userLang).T("msg_id")

// with domain, language 同时指定文本域、用户语言
t.D(domain).L(userLang).T("msg_id")
```

> more examples can be find at: [example_test.go](example_test.go)

## How to extract string 提取翻译文本
```bash
# if you use PoEdit, add a extractor
# 如果你使用 PoEdit，在设置-提取器中新增一个提取器
# Language: Go, *.go 语言填 Go 扩展名填 *.go 提取翻译的命令填写
# xgettext -C --add-comments=TRANSLATORS: --force-po -o %o %C %K %F
# 最后的三个输入框分别填写
# -k%k
# %f
# --from-code=%c
# keywords: 关键字这样设置：
# T:1;N:1,2;N64:1,2;X:2,1c;XN:2,3,1c;XN64:2,3,1c
xgettext -C --add-comments=TRANSLATORS: --force-po -kT -kN:1,2 -kX:2,1c -kXN:2,3,1c  *.go
```

## Done 已完成
- ✅ mo file 支持 mo 二进制文件
- ✅ extract from html templates 从模板文件中提取: [xtemplate](cmd/xtemplate/)
```bash
go install github.com/youthlin/t/cmd/xtemplate@latest
```

## Links 链接
- https://www.gnu.org/software/gettext/manual/html_node/index.html
- https://github.com/search?l=Go&q=gettext&type=Repositories
- https://github.com/antlr/antlr4/
- https://blog.gopheracademy.com/advent-2017/parsing-with-antlr4-and-go/
- https://xuanwo.io/2019/12/11/golang-i18n/ (中文)



## License
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fyouthlin%2Ft.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fyouthlin%2Ft?ref=badge_large)

Package and an accompanying tool to work with localized text

# go-i18n
![Build status](https://github.com/nicksnyder/go-i18n/workflows/Build/badge.svg) [![Report card](https://goreportcard.com/badge/github.com/nicksnyder/go-i18n/v2)](https://goreportcard.com/report/github.com/nicksnyder/go-i18n/v2) [![codecov](https://codecov.io/gh/nicksnyder/go-i18n/graph/badge.svg?token=A9aMfR9vxG)](https://codecov.io/gh/nicksnyder/go-i18n)

go-i18n is a Go [package](#package-i18n) and a [command](#command-goi18n) that helps you translate Go programs into multiple languages.

- Supports [pluralized strings](http://cldr.unicode.org/index/cldr-spec/plural-rules) for all 200+ languages in the [Unicode Common Locale Data Repository (CLDR)](https://www.unicode.org/cldr/charts/28/supplemental/language_plural_rules.html).
  - Code and tests are [automatically generated](https://github.com/nicksnyder/go-i18n/tree/main/internal/plural/codegen) from [CLDR data](http://cldr.unicode.org/index/downloads).
- Supports strings with named variables using [text/template](http://golang.org/pkg/text/template/) syntax.
- Supports message files of any format (e.g. JSON, TOML, YAML).

## Package i18n

[![Go Reference](https://pkg.go.dev/badge/github.com/nicksnyder/go-i18n/v2/i18n.svg)](https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2/i18n)

The i18n package provides support for looking up messages according to a set of locale preferences.

```go
import "github.com/nicksnyder/go-i18n/v2/i18n"
```

Create a Bundle to use for the lifetime of your application.

```go
bundle := i18n.NewBundle(language.English)
```

Load translations into your bundle during initialization.

```go
bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal)
bundle.LoadMessageFile("es.toml")
```

```go
// If use go:embed
//go:embed locale.*.toml
var LocaleFS embed.FS

bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal)
bundle.LoadMessageFileFS(LocaleFS, "locale.es.toml")
```

Create a Localizer to use for a set of language preferences.

```go
func(w http.ResponseWriter, r *http.Request) {
    lang := r.FormValue("lang")
    accept := r.Header.Get("Accept-Language")
    localizer := i18n.NewLocalizer(bundle, lang, accept)
}
```

Use the Localizer to lookup messages.

```go
localizer.Localize(&i18n.LocalizeConfig{
    DefaultMessage: &i18n.Message{
        ID: "PersonCats",
        One: "{{.Name}} has {{.Count}} cat.",
        Other: "{{.Name}} has {{.Count}} cats.",
    },
    TemplateData: map[string]interface{}{
        "Name": "Nick",
        "Count": 2,
    },
    PluralCount: 2,
}) // Nick has 2 cats.
```

## Command goi18n

[![Go Reference](https://pkg.go.dev/badge/github.com/nicksnyder/go-i18n/v2/goi18n.svg)](https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2/goi18n)

The goi18n command manages message files used by the i18n package.

```
go install -v github.com/nicksnyder/go-i18n/v2/goi18n@latest
goi18n -help
```

### Extracting messages

Use `goi18n extract` to extract all i18n.Message struct literals in Go source files to a message file for translation.

```toml
# active.en.toml
[PersonCats]
description = "The number of cats a person has"
one = "{{.Name}} has {{.Count}} cat."
other = "{{.Name}} has {{.Count}} cats."
```

### Translating a new language

1. Create an empty message file for the language that you want to add (e.g. `translate.es.toml`).
2. Run `goi18n merge active.en.toml translate.es.toml` to populate `translate.es.toml` with the messages to be translated.

   ```toml
   # translate.es.toml
   [HelloPerson]
   hash = "sha1-5b49bfdad81fedaeefb224b0ffc2acc58b09cff5"
   other = "Hello {{.Name}}"
   ```

3. After `translate.es.toml` has been translated, rename it to `active.es.toml`.

   ```toml
   # active.es.toml
   [HelloPerson]
   hash = "sha1-5b49bfdad81fedaeefb224b0ffc2acc58b09cff5"
   other = "Hola {{.Name}}"
   ```

4. Load `active.es.toml` into your bundle.

   ```go
   bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal)
   bundle.LoadMessageFile("active.es.toml")
   ```

### Translating new messages

If you have added new messages to your program:

1. Run `goi18n extract` to update `active.en.toml` with the new messages.
2. Run `goi18n merge active.*.toml` to generate updated `translate.*.toml` files.
3. Translate all the messages in the `translate.*.toml` files.
4. Run `goi18n merge active.*.toml translate.*.toml` to merge the translated messages into the active message files.

## For more information and examples:

- Read the [documentation](https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2).
- Look at the [code examples](https://github.com/nicksnyder/go-i18n/blob/main/i18n/example_test.go) and [tests](https://github.com/nicksnyder/go-i18n/blob/main/i18n/localizer_test.go).
- Look at an example [application](https://github.com/nicksnyder/go-i18n/tree/main/example).

## Translations of this document

Community translations of this document may be found in the [.github](.github) folder.

These translations are maintained by the community, and are not maintained by the author of this project.
They are not guaranteed to be accurate or up-to-date.

## License

go-i18n is available under the MIT license. See the [LICENSE](LICENSE) file for more info.


go-i18n

A words table and text resource library for Golang projects

go-words
========

[![Release](https://img.shields.io/github/v/release/saleh-rahimzadeh/go-words?filter=v1.2.0&label=Release)](https://github.com/saleh-rahimzadeh/go-words/releases/tag/v1.2.0)
![Go version](https://img.shields.io/github/go-mod/go-version/saleh-rahimzadeh/go-words)
[![Go Reference](https://pkg.go.dev/badge/github.com/saleh-rahimzadeh/go-words.svg)](https://pkg.go.dev/github.com/saleh-rahimzadeh/go-words)
[![Test Status](https://github.com/saleh-rahimzadeh/go-words/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/saleh-rahimzadeh/go-words/actions/workflows/test.yml?query=branch%3Amain)
![Coverage](https://img.shields.io/badge/Coverage-95.7%25-brightgreen)
[![codecov](https://codecov.io/gh/saleh-rahimzadeh/go-words/graph/badge.svg?token=O4EXLIR5ZN)](https://codecov.io/gh/saleh-rahimzadeh/go-words)
[![Go Report Card](https://goreportcard.com/badge/github.com/saleh-rahimzadeh/go-words)](https://goreportcard.com/report/github.com/saleh-rahimzadeh/go-words)
[![Awesome Go](https://awesome.re/mentioned-badge.svg)](https://awesome-go.com/translation)

The **go-words** is a words table and text resource library for Golang projects.

It provides text for your application messages, alerts, translations, prompts and ...



## Install

To install it:

```sh
go get -u github.com/saleh-rahimzadeh/go-words
```

Import:

```go
import (
  "github.com/saleh-rahimzadeh/go-words"
  "github.com/saleh-rahimzadeh/go-words/core"
)
/* OR */
import (
  gowords "github.com/saleh-rahimzadeh/go-words"
  core    "github.com/saleh-rahimzadeh/go-words/core"
)
```



## Source

A source is a string or a file that contains text lines, each separated by a line break.

Each line must contain a _key_ and _value_ pair, with the key separated from the value by a separator character.

A **key** must be a unique and searchable word.
It can be a single word or a phrase.

A **value** can be a single word, a phrase, or empty.

All leading and trailing whitespace of the key and value will be trimmed and removed upon loading.

A **separator** is a single delimiter character that separates the key and value in each line.
The default separator character is `=` (of `rune` type).
Other valid characters such as `|`, `:`, `;`, `,`, `.`, `?`, and `@` can also be used.

A line can also be a comment or an empty line.

A **comment** is a line that starts with a comment character.
The default comment character is `#` (of `rune` type), but other valid characters such as `|`, `:`, `;`, `,`, `.`, `?`, and `@` can also be used.

All comments and empty lines will be removed upon loading.

You cannot use the same character for both the separator and the comment.

Source Outline:

```txt
<key>=<value>
# comment line
```

Key and Value samples:

| Sample                                          | Result                                |
|-------------------------------------------------|---------------------------------------|
| `key1=value1`                                   | `key1=value1`                         |
| `key2 =value2`                                  | `key2=value2`                         |
| `key3= value3`                                  | `key3=value3`                         |
| `key4 = value4`                                 | `key4=value4`                         |
| `key5    =   value5`                            | `key5=value5`                         |
| `   key6    =      value6   `                   | `key6=value6`                         |
| `key7 multi words = value7 multi words`         | `key7 multi words=value7 multi words` |
| `  key8 multi words   =   value8 multi words  ` | `key8 multi words=value8 multi words` |
| `key9=`                                         | `key9=`                               |
| `key10`                                         | ERROR separator not found             |
| `= value11`                                     | ERROR key not found                   |
| `# comment`                                     | REMOVE                                |
| `#a long long long comment`                     | REMOVE                                |
| ` `  (empty line)                               | REMOVE                                |

Source sample:

```txt
App = MyApp
Version = 1.0
Descriptin = An enterprise application
# Config Section
size = 100,200,300,400
left location = 10
right location = 20
load_position = top left
```

Suppling source in code:

```go
// Source string
const stringSource string = `
App = MyApp
Version = 1.0
Descriptin = An enterprise application
# Config Section
size = 100,200,300,400
left location = 10
right location = 20
load_position = top left
`
// Source file
var fileSource *os.File
fileSource, err := os.Open("<path_to_string_file>")
```



## APIs

The **go-words** contain 3 different types of APIs, each with a different source and storage, so they have different performances, throughput, and resource usage.

| API               | Source     | Storage    | Source Validation    | Resource Usage |
|-------------------|------------|------------|----------------------|----------------|
| `WordsRepository` | `string`   | array      | On instantiation     | Memory         |
| `WordsCollection` | `string`   | map        | On instantiation     | Memory         |
| `WordsFile`       | `*os.File` | `*os.File` | Calling `CheckError` | CPU            |



## Instantiation

To create `WordsRepository` and `WordsCollection` instances use `NewWordsRepository`, `NewWordsCollection` functions and provide source, separator character and comment character.

`WordsRepository` example:

```go
func main() {
  const separator = '='
  const comment = '#'
  var err error

  var wrd gowords.WordsRepository
  wrd, err = gowords.NewWordsRepository(stringSource, separator, comment)
}
```

`WordsCollection` example:

```go
func main() {
  const separator = '='
  const comment = '#'
  var err error

  var wrd gowords.WordsCollection
  wrd, err = gowords.NewWordsCollection(stringSource, separator, comment)
}
```

These functions check and validate source, separator character, comment character and duplication on calling.

To create `WordsFile` instance use `NewWordsFile` function and provide source, separator character and comment character.

```go
func main() {
  const separator = '='
  const comment = '#'
  var err error

  var fileSource *os.File
  fileSource, err = os.Open("<path_to_string_file>")
  defer fileSource.Close()

  var wrd gowords.NewWordsFile
  wrd, err = gowords.NewWordsFile(fileSource, separator, comment)
}
```

This function check and validate separator character and comment character on calling.
To validate source and check duplication call `CheckError` method after instantiation.

```go
err := wrd.CheckError()
```

### Delimiters

You can use pre-declared characters for separator and comment delimiters of `github.com/saleh-rahimzadeh/go-words/core` package in instantiation.

- `core.Separator` for separator.
- `core.Comment` for comment.

```go
gowords.NewWordsRepository(stringSource, core.Separator, core.Comment)
gowords.NewWordsCollection(stringSource, core.Separator, core.Comment)
gowords.NewWordsFile(fileSource, core.Separator, core.Comment)
```



## Usage

All APIs implement `Words` interface.
This interface has two method `Get` and `Find` to search key and return value.

- The `Get` method search for a key then return value if found, else return empty string:

```go
var value string

value = wrd.Get("App")
println(value)  // OUTPUT: "MyApp"

value = wrd.Get("uknown_key")
println(value)  // OUTPUT: ""
```

- The `Find` method search for a key then return value and `true` boolean if found, else return empty string and `false` boolean:

```go
var value string
var found bool

value, found = wrd.Find("App")
println(value, found)  // OUTPUT: "MyApp", true

value, found = wrd.Find("uknown_key")
println(value, found)  // OUTPUT: "", false
```

Both methods validate input key on calling.

Visit "[github.com/saleh-rahimzadeh/go-words/blob/main/example_test.go](https://github.com/saleh-rahimzadeh/go-words/blob/main/example_test.go)" to see more samples.



## Suffixes

Using `WithSuffix` API to provide categorized words table and text resource, usually for internationalization and multi language texts.

To use `WithSuffix`:

1. Provide keys of source with desire suffixes.

   It's better to concate your key and suffixe with `_` character.

2. Define a variable of `Suffix` type from `core` package and instantiate `WithSuffix` API with a instance of `Words` interface (an instance of `NewWordsRepository`, `NewWordsCollection`, and `NewWordsFile`) and defined suffix.

3. Using `Get` and `Find` methods of `WithSuffix` instance to search for a name which applied suffix.

```go
func main() {
  const stringSource string = `
key1_EN = Value 1 English
key1_FA = Value 1 Farsi

key2_EN = Value 2 English
key2_FA = Value 2 Farsi

key3_EN = Value 3 English
key3_FA = Value 3 Farsi
`

  const EN core.Suffix = "_EN"
  const FA core.Suffix = "_FA"

  var wrd gowords.WordsRepository
  wrd, err := gowords.NewWordsRepository(stringSource, core.Separator, core.Comment)
  if err != nil {
    panic(err)
  }

  wordsEN, err := gowords.NewWithSuffix(wrd, EN)
  if err != nil {
    panic(err)
  }

  wordsFA, err := gowords.NewWithSuffix(wrd, FA)
  if err != nil {
    panic(err)
  }

  value1en := wordsEN.Get("key1")
  println(value1en)  // OUTPUT: "Value 1 English"

  value2en, found2en := wordsEN.Find("key2")
  println(value2en, found2en)  // OUTPUT: "Value 2 English", true

  value1fa := wordsFA.Get("key1")
  println(value1fa)  // OUTPUT: "Value 1 Farsi"

  value2fa, found2fa := wordsFA.Find("key2")
  println(value2fa, found2fa)  // OUTPUT: "Value 2 Farsi", true
}
```

The `NewWithSuffix` function validate suffix on calling.



## Annotations

Using `DoAnnotation` API to format value according to an annotation or a format specifier.

There are 3 types of annotations:
- Named: format value using named tokens like `{{name}}` by `GetNamed` and `FindNamed` methods.
- Indexed: format value using indexed tokens like `{{1}}` by `GetIndexed` and `FindIndexed` methods.
- Formatted: format value using formatted verbs (https://pkg.go.dev/fmt#hdr-Printing) like `%s` by `GetFormatted` and `FindFormatted` methods.

```go
func main() {
  const stringSource string = `
key_named = Application {{name}} , Version {{ver}}.
key_indexed = Application {{1}} , Version {{2}}.
key_formatted = Application %s , Version %d.
`

  var wRepository gowords.WordsRepository
  wRepository, err := gowords.NewWordsRepository(stringSource, core.Separator, core.Comment)
  if err != nil {
    panic(err)
  }

  words, err := gowords.NewDoAnnotation(wRepository)
  if err != nil {
    panic(err)
  }

  value1 := words.GetNamed("key_named", map[string]string{
    "name": "MyAppX",
    "age": "111",
  })
  fmt.Println(value1)  // OUTPUT: "Application MyAppX , Version 111"

  value2, found2 := words.FindNamed("key_named", map[string]string{
    "name": "MyAppZ",
    "age": "222",
  })
  fmt.Println(value2, found2)  // OUTPUT: "Application MyAppZ , Version 222", true

  value3 := words.GetIndexed("key_indexed", "MyAppQ", 333)
  fmt.Println(value3)  // OUTPUT: "Application MyAppQ , Version 333"

  value4, found4 := words.FindIndexed("key_indexed", "MyAppW", 444)
  fmt.Println(value4, found4)  // OUTPUT: "Application MyAppW , Version 444"

  value5 := words.GetFormatted("key_formatted", "MyAppN", 555)
  fmt.Println(value5)  // OUTPUT: "Application MyAppN , Version 555"

  value6, found6 := words.FindFormatted("key_formatted", "MyAppM", 666)
  fmt.Println(value6, found6)  // OUTPUT: "Application MyAppM , Version 666"
}
```



## Helper functions

There are some service functions, providing helper and utility functions, and also a simpler interface to working with APIs:

- `GetBy`: a helper to search for a name by suffix and using `Get` method of `Words` object.

```go
const EN core.Suffix = "_EN"
value1En := gowords.GetBy(wrd, "key1", EN)
```

- `FindBy`: a helper to search for a name by suffix and using `Find` method of `Words` object.

```go
const EN core.Suffix = "_EN"
value1En, found := gowords.FindBy(wrd, "key1", EN)
```



## Internationalization and Multi-Language

To internationalization your messages, alerts and texts, leverage `WithSuffix` API.

Prior to version 1.1.0, visit [Wiki Internationalization](https://github.com/saleh-rahimzadeh/go-words/wiki/Internationalization).



## Benchmark

```txt
goos: linux
goarch: amd64
pkg: github.com/saleh-rahimzadeh/go-words
cpu: Intel(R) Core(TM) i3 CPU  @ 2.93GHz
BenchmarkWordsCollection-4            20426679        62.60 ns/op          0 B/op       0 allocs/op
BenchmarkWordsRepository-4               65107        16248 ns/op          1 B/op       0 allocs/op
BenchmarkWordsFile-4                      9357       191994 ns/op      19280 B/op    1001 allocs/op
BenchmarkWordsFileUnsafe-4                5299       238233 ns/op      19280 B/op    1001 allocs/op
BenchmarkDoAnnotationNamed-4            352963         4641 ns/op        152 B/op       6 allocs/op
BenchmarkDoAnnotationIndexed-4          171255         6257 ns/op        498 B/op       9 allocs/op
BenchmarkDoAnnotationFormatted-4       1000000         1040 ns/op         64 B/op       1 allocs/op
PASS
coverage: 46.2% of statements
ok    github.com/saleh-rahimzadeh/go-words  6.400s
```



## Architecture Decisions

Architecture decision records (ADR) and design specifications:

| Index                        | Description                    |
| ---------------------------- | ------------------------------ |
| [01](doc/architecture-01.md) | Deciding on a parsing strategy |
| [02](doc/architecture-02.md) | Providing different storages   |


go-words

[![GitHub release](https://img.shields.io/github/release/leonelquinteros/gotext.svg)](https://github.com/leonelquinteros/gotext)
[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Gotext build](https://github.com/leonelquinteros/gotext/workflows/Gotext%20build/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/leonelquinteros/gotext)](https://goreportcard.com/report/github.com/leonelquinteros/gotext)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/leonelquinteros/gotext)](https://pkg.go.dev/github.com/leonelquinteros/gotext)


# Gotext

[GNU gettext utilities](https://www.gnu.org/software/gettext) for Go.


# Features

- Implements GNU gettext support in native Go.
- Complete support for [PO files](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) including:
  - Support for multiline strings and headers.
  - Support for variables inside translation strings using Go's [fmt syntax](https://golang.org/pkg/fmt/).
  - Support for [pluralization rules](https://www.gnu.org/software/gettext/manual/html_node/Translating-plural-forms.html).
  - Support for [message contexts](https://www.gnu.org/software/gettext/manual/html_node/Contexts.html).
- Support for MO files.
- Thread-safe: This package is safe for concurrent use across multiple goroutines.
- It works with UTF-8 encoding as it's the default for Go language.
- Unit tests available.
- Language codes are automatically simplified from the form `en_UK` to `en` if the first isn't available.
- Ready to use inside Go templates.
- Objects are serializable to []byte to store them in cache.
- Support for Go Modules.


# License

[MIT license](LICENSE)


# Documentation

Refer to package documentation at (https://pkg.go.dev/github.com/leonelquinteros/gotext)


# Installation

```
go get github.com/leonelquinteros/gotext
```

- There are no requirements or dependencies to use this package.
- No need to install GNU gettext utilities (unless specific needs of CLI tools).
- No need for environment variables. Some naming conventions are applied but not needed.


# Usage examples

## Using package for single language/domain settings

For quick/simple translations you can use the package level functions directly.

```go
import (
    "fmt"
    "github.com/leonelquinteros/gotext"
)

func main() {
    // Configure package
    gotext.Configure("/path/to/locales/root/dir", "en_UK", "domain-name")

    // Translate text from default domain
    fmt.Println(gotext.Get("My text on 'domain-name' domain"))

    // Translate text from a different domain without reconfigure
    fmt.Println(gotext.GetD("domain2", "Another text on a different domain"))
}

```

## Using dynamic variables on translations

All translation strings support dynamic variables to be inserted without translate.
Use the fmt.Printf syntax (from Go's "fmt" package) to specify how to print the non-translated variable inside the translation string.

```go
import (
    "fmt"
    "github.com/leonelquinteros/gotext"
)

func main() {
    // Configure package
    gotext.Configure("/path/to/locales/root/dir", "en_UK", "domain-name")

    // Set variables
    name := "John"

    // Translate text with variables
    fmt.Println(gotext.Get("Hi, my name is %s", name))
}

```


## Using Locale object

When having multiple languages/domains/libraries at the same time, you can create Locale objects for each variation
so you can handle each settings on their own.

```go
import (
    "fmt"
    "github.com/leonelquinteros/gotext"
)

func main() {
    // Create Locale with library path and language code
    l := gotext.NewLocale("/path/to/locales/root/dir", "es_UY")

    // Load domain '/path/to/locales/root/dir/es_UY/default.po'
    l.AddDomain("default")

    // Translate text from default domain
    fmt.Println(l.Get("Translate this"))

    // Load different domain
    l.AddDomain("translations")

    // Translate text from domain
    fmt.Println(l.GetD("translations", "Translate this"))
}
```

This is also helpful for using inside templates (from the "text/template" package), where you can pass the Locale object to the template.
If you set the Locale object as "Loc" in the template, then the template code would look like:

```
{{ .Loc.Get "Translate this" }}
```


## Using the Po object to handle .po files and PO-formatted strings

For when you need to work with PO files and strings,
you can directly use the Po object to parse it and access the translations in there in the same way.

```go
import (
    "fmt"
    "github.com/leonelquinteros/gotext"
)

func main() {
    // Set PO content
    str := `
msgid "Translate this"
msgstr "Translated text"

msgid "Another string"
msgstr ""

msgid "One with var: %s"
msgstr "This one sets the var: %s"
`

    // Create Po object
    po := gotext.NewPo()
    po.Parse(str)

    fmt.Println(po.Get("Translate this"))
}
```


## Use plural forms of translations

PO format supports defining one or more plural forms for the same translation.
Relying on the PO file headers, a Plural-Forms formula can be set on the translation file
as defined in (https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/Plural-forms.html)

```go
import (
    "fmt"
    "github.com/leonelquinteros/gotext"
)

func main() {
    // Set PO content
    str := `
msgid ""
msgstr ""

# Header below
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

msgid "Translate this"
msgstr "Translated text"

msgid "Another string"
msgstr ""

msgid "One with var: %s"
msgid_plural "Several with vars: %s"
msgstr[0] "This one is the singular: %s"
msgstr[1] "This one is the plural: %s"
`

    // Create Po object
    po := new(gotext.Po)
    po.Parse(str)

    fmt.Println(po.GetN("One with var: %s", "Several with vars: %s", 54, v))
    // "This one is the plural: Variable"
}
```


# Locales directories structure

The package will assume a directories structure starting with a base path that will be provided to the package configuration
or to object constructors depending on the use, but either will use the same convention to lookup inside the base path.

Inside the base directory where will be the language directories named using the language and country 2-letter codes (en_US, es_AR, ...).
All package functions can lookup after the simplified version for each language in case the full code isn't present but the more general language code exists.
So if the language set is `en_UK`, but there is no directory named after that code and there is a directory named `en`,
all package functions will be able to resolve this generalization and provide translations for the more general library.

The language codes are assumed to be [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes (2-letter codes).
That said, most functions will work with any coding standard as long the directory name matches the language code set on the configuration.

Then, there can be a `LC_MESSAGES` containing all PO files or the PO files themselves.
A library directory structure can look like:

```
/path/to/locales
/path/to/locales/en_US
/path/to/locales/en_US/LC_MESSAGES
/path/to/locales/en_US/LC_MESSAGES/default.po
/path/to/locales/en_US/LC_MESSAGES/extras.po
/path/to/locales/en_UK
/path/to/locales/en_UK/LC_MESSAGES
/path/to/locales/en_UK/LC_MESSAGES/default.po
/path/to/locales/en_UK/LC_MESSAGES/extras.po
/path/to/locales/en_AU
/path/to/locales/en_AU/LC_MESSAGES
/path/to/locales/en_AU/LC_MESSAGES/default.po
/path/to/locales/en_AU/LC_MESSAGES/extras.po
/path/to/locales/es
/path/to/locales/es/default.po
/path/to/locales/es/extras.po
/path/to/locales/es_ES
/path/to/locales/es_ES/default.po
/path/to/locales/es_ES/extras.po
/path/to/locales/fr
/path/to/locales/fr/default.po
/path/to/locales/fr/extras.po
```

And so on...


# Contribute

- Please, contribute.
- Use the package on your projects.
- Report issues on Github.
- Send pull requests for bugfixes and improvements.
- Send proposals on Github issues.



gotext

Transliterate Cyrillic → Latin in every possible way

# `Iuliia`
> Transliterate Cyrillic → Latin in every possible way

> This is the port of the incredible python library [iuliia](https://github.com/nalgeon/iuliia-py) made by @nalgeon

[![GoDoc](https://godoc.org/github.com/mehanizm/iuliia-go?status.svg)](https://pkg.go.dev/github.com/mehanizm/iuliia-go)
![Go](https://github.com/mehanizm/iuliia-go/workflows/Go/badge.svg)
[![codecov](https://codecov.io/gh/mehanizm/iuliia-go/branch/master/graph/badge.svg)](https://codecov.io/gh/mehanizm/iuliia-go)
[![Go Report](https://goreportcard.com/badge/github.com/mehanizm/iuliia-go)](https://goreportcard.com/report/github.com/mehanizm/iuliia-go)

Transliteration means representing Cyrillic data (mainly names and geographic locations) with Latin letters. It is used for international passports, visas, green cards, driving licenses, mail and goods delivery etc.

`Iuliia` makes transliteration as easy as:

```go
import iuliia "github.com/mehanizm/iuliia-go"

func main() {
    translated := iuliia.Wikipedia.Translate("Юлия Щеглова")
    fmt.Println(translated)
}

>> 'Yuliya Shcheglova'
```

## Why use `Iuliia`

- [20 transliteration schemas](https://github.com/nalgeon/iuliia) (rule sets), including all main international and Russian standards.
- Correctly implements not only the base mapping, but all the special rules for letter combinations and word endings (AFAIK, Iuliia is the only library which does so).
- Simple API and zero third-party dependencies.

## Installation

```sh
go get github.com/mehanizm/iuliia-go
```

`schemas` folder is the git submodule from [general repository](https://github.com/nalgeon/iuliia). You can add schemes manually and use generation to generate all code and tests:

```sh
go generate
```

## CLI interface

In the folder `cmd` you can find CLI app to play with the transliteration.

```sh
# run the app with help
./iuliia -h
> Usage of ./iuliia:
>   -schema string
>         choose schema name (default "wikipedia")
>   -show
>         showing list of the schemas

# simple run the program
./iuliia
> type phrase to translate with schema wikipedia:
> 'quit' to exit or 'help' to get help
> > 

# show help
> help
>> * show - to show all schemas
>> * change schema_name - to change schema
>> * quit - to quit the program
>> type phrase to translate with schema wikipedia:
>> 'quit' to exit or 'help' to get help

# translate
> Привет. Как у тебя дела?
>> Privet. Kak u tebya dela?

# show all schemas
> show
>> ala_lc:              ALA-LC transliteration schema.
>> ala_lc_alt:          ALA-LC transliteration schema.
>> bgn_pcgn:            BGN/PCGN transliteration schema
>> bgn_pcgn_alt:        BGN/PCGN transliteration schema
>> bs_2979:             British Standard 2979:1958 transliteration schema
>> bs_2979_alt:         British Standard 2979:1958 transliteration schema
>> gost_16876:          GOST 16876-71 (aka GOST 1983) transliteration schema
>> gost_16876_alt:      GOST 16876-71 (aka GOST 1983) transliteration schema
>> gost_52290:          GOST R 52290-2004 transliteration schema
>> gost_52535:          GOST R 52535.1-2006 transliteration schema
>> gost_7034:           GOST R 7.0.34-2014 transliteration schema
>> gost_779:            GOST 7.79-2000 (aka ISO 9:1995) transliteration schema
>> gost_779_alt:        GOST 7.79-2000 (aka ISO 9:1995) transliteration schema
>> icao_doc_9303:       ICAO DOC 9303 transliteration schema
>> iso_9_1954:          ISO/R 9:1954 transliteration schema
>> iso_9_1968:          ISO/R 9:1968 transliteration schema
>> iso_9_1968_alt:      ISO/R 9:1968 transliteration schema
>> mosmetro:            Moscow Metro map transliteration schema
>> mvd_310:             MVD 310-1997 transliteration schema
>> mvd_310_fr:          MVD 310-1997 transliteration schema
>> mvd_782:             MVD 782-2000 transliteration schema
>> scientific:          Scientific transliteration schema
>> telegram:            Telegram transliteration schema
>> ungegn_1987:         UNGEGN 1987 V/18 transliteration schema
>> wikipedia:           Wikipedia transliteration schema
>> yandex_maps:         Yandex.Maps transliteration schema
>> yandex_money:        Yandex.Money transliteration schema

# change schema
> change telegram
>> schema was changed to telegram
>> 
>> type phrase to translate with schema telegram:
>> 'quit' to exit or 'help' to get help
```

## Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Make sure to add or update tests as appropriate.

## License

[MIT](https://choosealicense.com/licenses/mit/)


iuliia-go

Flexible translation and humanization library for Go, based on the concepts behind gettext

# Spreak ![Test status](https://github.com/vorlif/spreak/workflows/Test/badge.svg) [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![PkgGoDev](https://pkg.go.dev/badge/github.com/vorlif/spreak)](https://pkg.go.dev/github.com/vorlif/spreak) [![Go Report Card](https://goreportcard.com/badge/github.com/vorlif/spreak)](https://goreportcard.com/report/github.com/vorlif/spreak) [![codecov](https://codecov.io/gh/vorlif/spreak/branch/main/graph/badge.svg?token=N1O0ZE1OFW)](https://codecov.io/gh/vorlif/spreak) ![MinVersion](https://img.shields.io/badge/Go-1.23+-blue)

Flexible translation and humanization library for Go, based on the concepts behind gettext. Requires Go 1.23+.

### Why another library?

There are already many good libraries for Go, which allow localizing an application.
However, I always came to a point where I was dissatisfied.
Either they use a self defined format, which could not be edited with common tools.
Some libraries only support one language at a time or are using a lot of mutexes.
And no tool could easily extract the strings to be translated.
I wanted to solve these problems for myself, and so spreak was born.

### Features

* Built-in support for `po`, `mo` and [`json`](./examples/features/jhttptempl) files
* Support for `fs.FS` (e.g. `embed`)
* Goroutine-safe and lock free through immutability
* [Powerful extractor](https://github.com/vorlif/xspreak#xspreak) for strings to simplify the localization process
  (with **support for templates**)
* [Support](https://pkg.go.dev/github.com/vorlif/spreak#hdr-Plurals)
  for [gettext](https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html)
and [CLDR v47](https://cldr.unicode.org/index/cldr-spec/plural-rules) plural rules.
* Support of bilingual and monolingual formats

### Usage

Using spreak is easy. First, use go get to install the latest version of the library.

```shell
go get -u github.com/vorlif/spreak
```

After that, spreak offers you a comprehensive interface to load and query your translations.

```go
package main

import (
	"fmt"

	"golang.org/x/text/language"

	"github.com/vorlif/spreak"
	"github.com/vorlif/spreak/localize"
)

func main() {
	// Create a bundle that loads the translations for the required languages.
	// Typically, you only need one bundle in an application.
	bundle, err := spreak.NewBundle(
		// Set the language used in the program code/templates
		spreak.WithSourceLanguage(language.English),
		// Set the path from which the translations should be loaded
		spreak.WithDomainPath(spreak.NoDomain, "./locale"),
		// Specify the languages you want to load
		spreak.WithLanguage(language.German, language.Spanish, language.Chinese),
	)
	if err != nil {
		panic(err)
	}

	// Create a Localizer to select the language to translate.
	t := spreak.NewLocalizer(bundle, language.Spanish)

	// Translate
	fmt.Println(t.Get("Hello world"))
	fmt.Println(t.NGetf("I have %d dog", "I have %d dogs", 2, 2))
	fmt.Println(t.Localize(GetPlanet()))

	// Output: 
	// Hola Mundo
	// Tengo 2 perros
	// No conozco ningún planeta
}

func GetPlanet() *localize.Message {
	return &localize.Message{
		Singular: "I do not know any planet",
		Plural:   "I do not know any planets",
	}
}
```

### Extract strings

Strings for the translations can be extracted via the [command line program xspreak](https://github.com/vorlif/xspreak).
Use a [pre-built binary](https://github.com/vorlif/xspreak/releases/latest) or install it from source:

```bash
go install github.com/vorlif/xspreak@latest
```

Tests installation with:

```bash
xspreak --help
```

xspreak extracts the strings from the program code and creates a template which can be used for new translations.
Before you extract your strings, you have to decide on a format.

It can either create a `.pot` (PO Templates) file in po format or a `.json` file.
If you are not sure which format to use, I would recommend you to use `po` format,
because it is supported by almost all translation programs, which makes your life and the life of your translators much
easier.

With `-D` you specify the path to your source code and with `-p` the one where the translation template should be saved.

```bash
# for .pot
xspreak -D path/to/source/ -p path/to/source/locale
# for .json
xspreak -D path/to/source/ -p path/to/source/locale -f json
```

This creates a new `.pot` or `.json` file representing the translation template.

### Translate

**po files**

The generated POT files can be easily imported by most translation tools.
If you are dealing with Po files for the first time,
I recommend the application [Poedit](https://poedit.net/) for a quick start.

After translation `.po` or `.mo` files are generated, which are used by spreak for looking up translations.
Attention, do not translate the `.pot` file directly, as this is only a template.

**json files**

You can open and edit the JSON files with any text editor.
The extracted template always uses only the plural categories `one` and `other`. 
To create a template with the plural categories suitable for your language, you can use xspreak.

```bash
xspreak merge -i locale/template.json -o locale/de.json -l de
```

### Update translation files

> :warning: It would be wise before making any move to **keep a backup**.

When you add, edit or delete text in your program code, you should also update the translation files.
To achieve this, you must first update the template:

```bash
# for .pot
xspreak -D path/to/source/ -p path/to/source/locale
# for .json
xspreak -D path/to/source/ -p path/to/source/locale -f json
```

This creates a new `.pot` or `.json` file representing the *new* translation template.

**po files**

For PO files, almost every translation tool offers the possibility to update the files from a POT file.
With Poedit you can do it via `Translation -> Update from POT file`.
If you use the gettext utilities, you can use `msgmerge -U es.po template.pot`.
For all other tools, it is worth taking a look at the documentation.

**json files**

For JSON files, xspreak offers a simple way to update the translation files.

```bash
xspreak merge -i locale/template.json -o locale/de.json -l de
```

This copies new keys and existing translations from `template.json` to `de.json` and deletes keys from `de.json`
that are not present in `template.json`.

### Structure translations

How you structure the files with the translations is up to you.
Assuming you load the domain `"helloworld"` from the path `"./locale"` and the language `language.Spanish`

```go
spreak.WithDomainPath("helloworld", "./locale"),
spreak.WithLanguage(language.Spanish),
```

Then spreak searches for the following files by default

```text
./locale/es/helloworld.po
./locale/helloworld/es.po
./locale/es.po
./locale/LC_MESSAGES/es/helloworld.po
```

Where `es` is an example from the list `[es-ES, es_ES, spa, es]` and the file extension `.po` is an example from the
list `[po, mo, json]`.
If you don't like this behavior, you can implement your own [`Resolver`](examples/features/resolver/main.go).
For special cases you can also implement your own [`Loader`](examples/features/loaders/main.go).

### How to use in tests?

Just create a `Bundle` without options.
This will never return an error and can be used to create `Localizer` which then simply return the input.

```go
bundle, _ := spreak.NewBundle()
t := spreak.NewLocalizer(bundle, language.English)
```

### What's next

* Read what you can extract with [xspreak](https://github.com/vorlif/xspreak#xspreak)
* Take a look in the [examples folder](./examples) for more examples of using spreak.
* Use it!

## Package humanize

**Attention**: For a clean separation and easier maintenance, the `humanize` package has been separated
into a separate library and can now be found under https://github.com/vorlif/humanize.

The package in this repository is marked as deprecated and will be removed with the release of v2.

To change the library, simply
follow [the migration guide](https://github.com/vorlif/humanize?tab=readme-ov-file#migrate-from-spreak).

### Add translations

If you would like to add a translation or add a new language, **do not do so in this repository**.
The translations in this repository are automatically generated from the Django translations and additions should also
be made there.
Use the following link to do so: https://www.transifex.com/django/django/.
For all non-translation related errors, this repository must be used.

## License

spreak is available under the MIT license. See the [LICENSE](LICENSE) file for more info.
The translations of the `humanize` packages are licensed
under [Django's BSD license](https://raw.githubusercontent.com/django/django/main/LICENSE).


The Best Go Libraries For Natural Language Processing - Translation (9)