gdev-i18n

command module
v0.0.0-...-5c85043 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2022 License: MIT Imports: 16 Imported by: 0

README

gdev-i18n

gdev-i18n is a golang international language pack tool, refer to the official stinger tool

golang国际化语言包工具，参考了官方stringer工具

一、Usage/使用

1.1、Build/下载编译

因未使用ioutil包，构建二进制可执行文件要求go最低版本1.16，因生成的代码使用了context.Context，生成的代码支持1.7及其以上版本

Because ioutil is not used, to build a binary executable file the minimum version of Go 1.16 is required, because of the use of context.Context the generated code can be used for version 1.7 and above

go Version 1.16 and above for install/使用go1.16及其以上版本编译安装

go install github.com/gqgo/gdev-i18n@latest

或者也可以直接从release下载对应平台编译好的二进制 可执行程序放置于环境变量目录下 即可使用：https://github.com/gqgo/gdev-i18n/releases

The example directory gives an example of usage witch used gomod

example目录给出一种示例，该示例使用了gomod，请参考

cd example
# Note that the files generated in `example` directory are ignored, 
# you need to execute the following command to generate
go generate ./...
go run main.go

开发调试可以使用make指令，可以调试test目录下的多个示例

You can use the make command for development and debugging, can debug multiple examples in the test directory

make debug

1.2、Define Numerical shaping Constant/定义整数数值型常量

type Code int

const (
    ERROROFYOU Code = iota + 1   
    ERROROFMINE Code = 10000
)

Numerical shaping: such as int, uint, uint32, etc.

1.3、Define Language Package/定义语言包

Use only TOML format files

  • 定义语言包目录：语言包目录位于定义常量源码文件的同级目录下的子目录，默认语言包目录名称为i18n
  • The language package directory is located in a subdirectory of the same level directory that defines the constant source code file. The default language package directory name is i18n
  • 语言包目录下使用TOML文件定义i18n翻译的键值对；
  • Use TOML files in the language package directory to define key-value pairs for i18n translation
  • 语言包目录下若使用子目录，则子目录名将被作为语言类型标记，子目录下TOML文件名和文件数目不做限制，例如：en；
  • If a subdirectory is used in the language package directory, the name of the subdirectory will be marked as the language type, TOML file name and number of files in subdirectories are not limited. For example: en;
  • 语言包目录下不使用子目录直接定义TOML文件的，则TOML文件的文件名将被作为语言类型标记，例如：en.toml；
  • If the TOML file is directly defined in language package directory, the file name of the TOML file will be marked as the language type. For example: en.toml;
  • 语言包键值对的键名使用常量字面量，上述例子中ERROROFYOU就将作为键名；
  • Use constant literals for the key names of language pack key-value pairs. In the above example, ERROROFYOU will be used as the key name

1.4、代码生成/Generate Code

Go to the directory that defines the constant under the terminal and execute it

终端下进入到定义常量的目录直接执行：

$GOPATH/bin/gdev-i18n -type Code -tomlpath i18n

You can also use the go generate command directly in the constant source code

你也可以配合go generate指令直接在定于常量的源码里使用

// write this code in your golang source code, then use `go generate` command
//go:generate $GOPATH/bin/gdev-i18n -type Code -tomlpath i18n

1.5、开发调试/Dev and debugging

可以使用-check指令参数核对语言包缺失的键值对

You can use the -check command to check the missing key-value pairs of the language pack

$GOPATH/bin/gdev-i18n -type Code -tomlpath i18n -check

带-check的命令执行后如果有缺失键值对或无用键值对，则可能会输出如下提示以协助开发

After the command with -check is executed, if there are missing key-value pairs or useless key-value pairs, the following prompt may be output to assist development

gdev-i18n: Check Fail
gdev-i18n: The missing key-value pair information as follows
gdev-i18n: You can copy and fill it to the corresponding TOML file
************TYPE `Single` locale `zh-hk` missing key-value pair************
Sig01=""
Sig02=""
Sig03=""
gdev-i18n: Check Warning
gdev-i18n: key-value pairs that will not be used because there is no corresponding constant
gdev-i18n: You can delete the key-value pairs in the corresponding TOML file
************Can be deleted TOML keys of locale `en`************
HELLO
WORLD

1.6、指令详情/command details

Get more help information about commands

获取更多命令使用帮助信息：

$GOPATH/bin/gdev-i18n --help

Usage of gdev-i18n:
        gdev-i18n [flags] -type T [directory]
        gdev-i18n [flags] -type T -tomlpath DIR -check # just for check
        gdev-i18n [flags] -type T -defaultlocale LOCALE -tomlpath DIR files... # Must be a single package
For more information, see:
        https://github.com/gqgo/gdev-i18n
Flags:
  -check
        Check missing or useless key-value pairs in TOML
  -ctxkey string
        key used by context.Value for get locale; default i18nLocale
  -defaultlocale string
        set default locale name; default naturally sorted first
  -output string
        output file name; default srcdir/<type>_i18n_string.go
  -tags string
        comma-separated list of build tags to apply
  -tomlpath string
        set toml i18n file path; default srcdir/i18n
  -type string
        comma-separated list of type names; must be set

If your GOBIN directory has been added to the environment variable, the above $GOPATH/bin/ can also be omitted

如果你的GOBIN目录已加入环境变量，上述$GOPATH/bin/也是可以省略的

1.7、调用/Code call

For example

Directory tree

.
├── i18n
│     └── en.toml
│     ├── zh_cn.toml
│     └── zh_hk
│     │     ├── user.toml
│     │     └── merchant.toml
└── code.go

Given the name of a (signed or unsigned) integer type T that has constants defined at file code.go

package foo

type Pill int

const (
    Placebo Pill = iota
    Aspirin
    Ibuprofen
    Paracetamol
    Acetaminophen = Paracetamol // NOTE: with the same value will be ignored, do not use same value
)

Define TOML key-value pairs in all locale TOML file, example for i18n/en.toml

Placebo="en locale Placebo"
Aspirin="en locale Aspirin"
Ibuprofen="en locale Ibuprofen"
Acetaminophen="en locale Acetaminophen"

running this command

gdev-i18n -type=Pill

in the same directory will create the file pill_i18n_string.go, in package foo, containing a definition of, and a struct I18nPillErrorWrap will also be created

type Pill Added method

func (Pill) String() string
func (Pill) Error() string
func (Pill) Wrap(err error, locale string, args ...interface{}) I18nPillErrorWrap
func (Pill) WrapWithContext(ctx context.Context, err error, args ...interface{}) I18nPillErrorWrap
func (Pill) IsLocaleSupport(locale string) bool
func (Pill) Lang(ctx context.Context, args ...interface{}) string
func (Pill) Trans(locale string, args ...interface{}) string

Now you can use type Pill's methods with the locale identifier to get the translation value

因部分翻译文本中可能会使用诸如%s类型的替换佔位符在代码中实时更改，建议规划好整形数值区间， 某些区间的值专门用于替换%s的。

Because some translation texts may use replacement placeholders such as %s to change in the code in real time, it is recommended to plan the integer value range, and this range values are specifically used to replace %s.

二、TOML规范支持/TOML Specification Support

TOML Link : https://toml.io/en/

  • TOML文件仅支持Basic strings形式的字符串键值对，形如：Key="value"，也就意味着一对键值对只能位于一行
  • TOML file only support Basic strings key/value, shaped like Key="value", do not support Multi-line basic strings, pair K/V only be located on one line
  • TOML键名仅支持裸键，键名只能包含ASCII字母，ASCII数字，下划线和短横线（A-Za-z0-9_-）
  • TOML file only support Bare keys,only contain ASCII letters, ASCII digits, underscores, and dashes(A-Za-z0-9_-)
  • 区块也就是TOML官方的Table将被忽略
  • The block section, which is the TOML official Table, will be ignored
  • 支持#开头的注释，注释将被忽略
  • Support comments starting with #, comments will be ignored

Documentation

Overview

Copyright 2014 The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

The above is the copyright information reserved by reference stringer REF: https://github.com/golang/tools/tree/master/cmd/stringer

Copyright 2021 The team gqgo Authors. All rights reserved. Use of this source code is governed by a MIT License license that can be found in the LICENSE file.

gdev-i18n is a tool to automate the creation of methods that satisfy the fmt.Stringer, error interface. Given the name of a (signed or unsigned) integer type T that has constants defined, gdev-i18n will create a new self-contained Go source file implementing 

func (t T) String() string
func (t T) Error() string
func (t T) TransErrorDetail(args ...interface{}) I18nTErrorWrap
func (t T) Wrap(err error, locale string, args ...interface{}) *I18nTErrorWrap
func (t T) WrapWithContext(ctx context.Context, err error, args ...interface{}) *I18nTErrorWrap
func (t T) IsLocaleSupport(locale string) bool
func (t T) Lang(ctx context.Context, args ...interface{}) string
func (t T) Trans(locale string, args ...interface{}) string
--- Noted ---
1. I18nTErrorWrap struct is an error wrap type
2. All type interface{} for named param ...args interface{}, can only use variable typed T or string

wrapped type I18nTErrorWrap implement method list 

func (t *I18nTErrorWrap) Translate() string
func (t *I18nTErrorWrap) String() string
func (t *I18nTErrorWrap) Error() string
func (t *I18nTErrorWrap) Format() string
func (t *I18nTErrorWrap) Value() Code
func (t *I18nTErrorWrap) Unwrap() error
--- you can see generated file get more detail ---

As you can see type I18nTErrorWrap also is an typed Error, and can wrap/unwrap your business logic error The file is created in the same package and directory as the package that defines T. It has helpful defaults designed for use with go generate.

fmt.Stringer works best with constants that are consecutive values such as created using iota, but creates good code regardless.

For example, given this snippet, 

package painkiller

type Pill int

const (
	Placebo Pill = iota
	Aspirin
	Ibuprofen
	Paracetamol
	Acetaminophen = Paracetamol // NOTE: with the same value will be ignored, do not use same value
)

Create an i18n directory in the same level directory of the source code, create a TOML file use locale name as the file name in the directory, and define the text corresponding to these constants

For example, 

.
├── i18n
│     └── en.toml
│     ├── zh_cn.toml
│     └── zh_hk
│     │     ├── user.toml
│     │     └── merchant.toml
└── pill.go

Define TOML key-value pairs in the file srcdir/i18n/en.toml

Placebo="en locale Placebo" Aspirin="en locale Aspirin" Ibuprofen="en locale Ibuprofen" Acetaminophen="en locale Acetaminophen"

Similarly, other TOML files are also defined

The above directory tree defines three locale: en, zh_cn AND zh_hk As you can see, the TOML file name in the i18n directory is used as the locale identifier, the subdirectory name under the directory i18n will be used as the locale identifier, and the TOML file name in the subdirectory is no longer restricted The directory name i18n can be overridden with the -tomlpath flag.

running this command 

gdev-i18n -type=Pill

in the same directory will create the file pill_i18n_string.go, in package painkiller, containing a definition of, and a struct I18nPillErrorWrap will also be created 

func (Pill) String() string
func (Pill) Error() string
func (Pill) Wrap(err error, locale string, args ...interface{}) *I18nPillErrorWrap
func (Pill) WrapWithContext(ctx context.Context, err error, args ...interface{}) *I18nPillErrorWrap
func (Pill) IsLocaleSupport(locale string) bool
func (Pill) Lang(ctx context.Context, args ...interface{}) string
func (Pill) Trans(locale string, args ...interface{}) string
// also wrap/unwrap type I18nPillErrorWrap generated
type I18nPillErrorWrap struct {
	err    error         // wrap another error
	origin Pill          // custom shaping type Val
	locale string        // i18n locale set
	args   []interface{} // formatted output replacement component
}
// you can see your generate file get more detail for this method
func (t *I18nPillErrorWrap) Translate() string
func (t *I18nPillErrorWrap) String() string
func (t *I18nPillErrorWrap) Error() string
func (t *I18nPillErrorWrap) Format() string
func (t *I18nPillErrorWrap) Value() Code
func (t *I18nPillErrorWrap) Unwrap() error

That methods will translate the value of a Pill constant to the string representation of the respective value define in TOML file

Typically this process would be run using go generate, like this: 

//go:generate gdev-i18n -type=Pill

If multiple constants have the same value, the lexically first matching name will be used (in the example, Acetaminophen will print defined in TOML value of key Paracetamol). NOTE: It is not recommended to use constants of the same value

With no arguments, it processes the package in the current directory. Otherwise, the arguments must name a single directory holding a Go package or a set of Go source files that represent a single Go package.

The -check flag is used to check missing or useless key-value pairs in TOML files without generating files. Output can be used to help check TOMl files

The -tomlpath flag is used to specify the TOML file storage path. If is omitted, the default value is i18n

The -ctxkey flag is used to specify the key to obtain the current locale from context.Context If is omitted, the default value is i18nLocale

The -defaultlocale flag is used to specify the default language locale. The default language locale will be used when obtaining the translation value for String, Error methods and without or invalid the language locale for Trans, Lang methods If is omitted, the default is the one first of naturally sorted list

The -type flag accepts a comma-separated list of types so a single run can generate methods for multiple types. The default output file is t_i18n_stringer.go, where t is the lower-cased name of the first type listed. It can be overridden with the -output flag.

Source Files

View all Source files

Directories

Path Synopsis
lang

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.