DeineAgenturUG/gotext
1
0
Fork 0
Code Issues Pull Requests Releases 2 Wiki Activity

Add Github Build action badge

Browse Source
This commit is contained in:
Leonel Quinteros Carbano
2020-04-15 22:08:55 -03:00
parent d26d707c73
commit f7464201e6
1 changed files with 36 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
README.md
View File

@@ -1,12 +1,13 @@
[![GitHub release](https://img.shields.io/github/release/leonelquinteros/gotext.svg)](https://github.com/leonelquinteros/gotext) [![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) [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![GoDoc](https://godoc.org/github.com/leonelquinteros/gotext?status.svg)](https://godoc.org/github.com/leonelquinteros/gotext) [![GoDoc](https://godoc.org/github.com/leonelquinteros/gotext?status.svg)](https://godoc.org/github.com/leonelquinteros/gotext)
![Gotext build](https://github.com/leonelquinteros/gotext/workflows/Gotext%20build/badge.svg?branch=master)
[![Build Status](https://travis-ci.org/leonelquinteros/gotext.svg?branch=master)](https://travis-ci.org/leonelquinteros/gotext) [![Build Status](https://travis-ci.org/leonelquinteros/gotext.svg?branch=master)](https://travis-ci.org/leonelquinteros/gotext)
[![Go Report Card](https://goreportcard.com/badge/github.com/leonelquinteros/gotext)](https://goreportcard.com/report/github.com/leonelquinteros/gotext) [![Go Report Card](https://goreportcard.com/badge/github.com/leonelquinteros/gotext)](https://goreportcard.com/report/github.com/leonelquinteros/gotext)
# Gotext # Gotext
[GNU gettext utilities](https://www.gnu.org/software/gettext) for Go. [GNU gettext utilities](https://www.gnu.org/software/gettext) for Go.
# Features # Features
@@ -17,8 +18,8 @@
- Support for variables inside translation strings using Go's [fmt syntax](https://golang.org/pkg/fmt/). - 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 [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 [message contexts](https://www.gnu.org/software/gettext/manual/html_node/Contexts.html).
- Support for MO files. - Support for MO files.
- Thread-safe: This package is safe for concurrent use across multiple goroutines. - 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. - It works with UTF-8 encoding as it's the default for Go language.
- Unit tests available. - Unit tests available.
- Language codes are automatically simplified from the form `en_UK` to `en` if the first isn't available. - Language codes are automatically simplified from the form `en_UK` to `en` if the first isn't available.
@@ -37,15 +38,15 @@
Refer to the Godoc package documentation at (https://godoc.org/github.com/leonelquinteros/gotext) Refer to the Godoc package documentation at (https://godoc.org/github.com/leonelquinteros/gotext)
# Installation # Installation
``` ```
go get github.com/leonelquinteros/gotext go get github.com/leonelquinteros/gotext
``` ```
- There are no requirements or dependencies to use this package. - 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 to install GNU gettext utilities (unless specific needs of CLI tools).
- No need for environment variables. Some naming conventions are applied but not needed. - No need for environment variables. Some naming conventions are applied but not needed.
## Version vendoring ## Version vendoring
@@ -103,19 +104,19 @@ Refer to it as gotext.
# Locales directories structure # Locales directories structure
The package will assume a directories structure starting with a base path that will be provided to the package configuration 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. 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, ...). 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. 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`, 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. 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). 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. 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. Then, there can be a `LC_MESSAGES` containing all PO files or the PO files themselves.
A library directory structure can look like: A library directory structure can look like:
``` ```
/path/to/locales /path/to/locales
@@ -140,7 +141,7 @@ A library directory structure can look like:
/path/to/locales/fr /path/to/locales/fr
/path/to/locales/fr/default.po /path/to/locales/fr/default.po
/path/to/locales/fr/extras.po /path/to/locales/fr/extras.po
``` ```
And so on... And so on...
@@ -160,10 +161,10 @@ import (
func main() { func main() {
// Configure package // Configure package
gotext.Configure("/path/to/locales/root/dir", "en_UK", "domain-name") gotext.Configure("/path/to/locales/root/dir", "en_UK", "domain-name")
// Translate text from default domain // Translate text from default domain
fmt.Println(gotext.Get("My text on 'domain-name' domain")) fmt.Println(gotext.Get("My text on 'domain-name' domain"))
// Translate text from a different domain without reconfigure // Translate text from a different domain without reconfigure
fmt.Println(gotext.GetD("domain2", "Another text on a different domain")) fmt.Println(gotext.GetD("domain2", "Another text on a different domain"))
} }
@@ -172,8 +173,8 @@ func main() {
## Using dynamic variables on translations ## Using dynamic variables on translations
All translation strings support dynamic variables to be inserted without translate. 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. Use the fmt.Printf syntax (from Go's "fmt" package) to specify how to print the non-translated variable inside the translation string.
```go ```go
import ( import (
@@ -184,10 +185,10 @@ import (
func main() { func main() {
// Configure package // Configure package
gotext.Configure("/path/to/locales/root/dir", "en_UK", "domain-name") gotext.Configure("/path/to/locales/root/dir", "en_UK", "domain-name")
// Set variables // Set variables
name := "John" name := "John"
// Translate text with variables // Translate text with variables
fmt.Println(gotext.Get("Hi, my name is %s", name)) fmt.Println(gotext.Get("Hi, my name is %s", name))
} }
@@ -197,7 +198,7 @@ func main() {
## Using Locale object ## Using Locale object
When having multiple languages/domains/libraries at the same time, you can create Locale objects for each variation 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. so you can handle each settings on their own.
```go ```go
@@ -209,23 +210,23 @@ import (
func main() { func main() {
// Create Locale with library path and language code // Create Locale with library path and language code
l := gotext.NewLocale("/path/to/locales/root/dir", "es_UY") l := gotext.NewLocale("/path/to/locales/root/dir", "es_UY")
// Load domain '/path/to/locales/root/dir/es_UY/default.po' // Load domain '/path/to/locales/root/dir/es_UY/default.po'
l.AddDomain("default") l.AddDomain("default")
// Translate text from default domain // Translate text from default domain
fmt.Println(l.Get("Translate this")) fmt.Println(l.Get("Translate this"))
// Load different domain // Load different domain
l.AddDomain("translations") l.AddDomain("translations")
// Translate text from domain // Translate text from domain
fmt.Println(l.GetD("translations", "Translate this")) 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. 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: If you set the Locale object as "Loc" in the template, then the template code would look like:
``` ```
{{ .Loc.Get "Translate this" }} {{ .Loc.Get "Translate this" }}
@@ -234,7 +235,7 @@ If you set the Locale object as "Loc" in the template, then the template code wo
## Using the Po object to handle .po files and PO-formatted strings ## Using the Po object to handle .po files and PO-formatted strings
For when you need to work with PO files and 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. you can directly use the Po object to parse it and access the translations in there in the same way.
```go ```go
@@ -255,11 +256,11 @@ msgstr ""
msgid "One with var: %s" msgid "One with var: %s"
msgstr "This one sets the var: %s" msgstr "This one sets the var: %s"
` `
// Create Po object // Create Po object
po := new(gotext.Po) po := new(gotext.Po)
po.Parse(str) po.Parse(str)
fmt.Println(po.Get("Translate this")) fmt.Println(po.Get("Translate this"))
} }
``` ```
@@ -299,21 +300,21 @@ msgid_plural "Several with vars: %s"
msgstr[0] "This one is the singular: %s" msgstr[0] "This one is the singular: %s"
msgstr[1] "This one is the plural: %s" msgstr[1] "This one is the plural: %s"
` `
// Create Po object // Create Po object
po := new(gotext.Po) po := new(gotext.Po)
po.Parse(str) po.Parse(str)
fmt.Println(po.GetN("One with var: %s", "Several with vars: %s", 54, v)) fmt.Println(po.GetN("One with var: %s", "Several with vars: %s", 54, v))
// "This one is the plural: Variable" // "This one is the plural: Variable"
} }
``` ```
# Contribute # Contribute
- Please, contribute. - Please, contribute.
- Use the package on your projects. - Use the package on your projects.
- Report issues on Github. - Report issues on Github.
- Send pull requests for bugfixes and improvements. - Send pull requests for bugfixes and improvements.
- Send proposals on Github issues. - Send proposals on Github issues.