Golang SDK

GoLang SDK

使用前请先确定已了解 Starling 产品的相关功能，已注册并加入到某个项目中，下文均以此为前提。Go语言版本1.13及以上。

安装

Starling Golang SDK 在github开源方式提供，详见 https://github.com/volcengine/i18n-sdk-golang ，可通过如下方式下载安装：

go get -v github.com/volcengine/i18n-sdk-golang

创建客户端

获取当前待拉取文案的所在项目名称、空间名称和项目的appKey，使用如下接口创建客户端：

import (
	"context"
	i18ngo "github.com/volcengine/i18n-sdk-golang"
)

client := i18ngo.NewClient(
	context.Background(),
    "${YOUR_PROJECT_NAME}",
    "${YOUR_NAMESPACE}",
    WithAppKey("${YOUR_APP_KEY}"))

项目名、空间名称、appKey 从 Starling 平台获取，请保证正确，appKey 用于身份鉴权，为安全考虑建议不要使用明文出现在代码中。

获取文案

提供两种方式获取已翻译的文案：获取给定项目、给定空间的整个文案包 或者 指定获取单个key的文案。

获取单个文案

通过指定key和语言，以及可选的模式（如灰度发布的文案，功能暂未支持，可先忽略），对于语言可指定兜底语言或者指定版本。具体接口定义如下：

GetText(key string, lang string, mode ...ModeType) (val string, lang string)
GetTextWithFallback(key string, langs []string, mode ...ModeType) (val string, lang string)
GetTextWithFallbackVersion(key, lang string, fb FallbackType, ver int, mode ...ModeType) (val string, lang string, version int64)

调用实例：

val, lang := client.GetText("abc", "en")

获取文案包

通过指定语言以及可选的模式（如灰度发布的文案，功能暂未支持，可先忽略）获取整个文案包，对于语言可指定兜底语言或者指定版本。文案包以 key=value 对的形式返回，具体接口定义如下：

GetPackage(lang string, mode ...ModeType) (map[string]string, string, int64)
GetPackageWithFallback(langs []string, mode ...ModeType) (map[string]string, string, int64)
GetPackageWithFallbackVersion(lang string, fb FallbackType, ver int, mode ...ModeType) (map[string]string, string, int64)

调用实例：

pkg, ver := client.GetPackage("zh-Hans")

选项设置

创建客户端时，提供了多种选项可进行细粒度控制，默认可忽略，如使用这些详细配置请务必清楚具体选项的含义。

• WithHTTPDomain(domain string): 设置文案拉取的远程域名，默认为Starling提供的公网域名，如有本地代理可通过该选项设置
• WithEnableHTTPs(enable bool): 设置文案拉取是否使用https
• WithHTTPTimeout(timeout int): 设置单次请求进行文案拉取时的超时时间
• WithEnableSimilar(similar bool): 设置是否让SDK自动进行相似语言的兜底处理
• WithEnableFallback(fallback bool): 设置是否使用全局兜底
• WithOperator(operator string): 设置当前调用SDK拉取文案时的用户标识，可用于审计
• WithRetryPolicy(policy RetryPolicy): 设置请求失败时进行重试的策略，具体包括如下两种：
  • NewNoRetryPolicy(): 不使用重试
  • NewBackoffRetryPolicy(maxRetry int, maxDelayMs, intervalMs int64): 使用指数回退重试，提供最大重试次数、指数重试间隔、最大间隔参数
• WithLogger(logger Logger): 设置日志处理器，可自行处理SDK内部的细节日志
• WithMetricer(metricer Metricer): 设置监控处理器，可自行处理SDK内部的调用监控信息
• WithProxyer(proxyer Proxyer): 设置获取文案的proxy，可用于本地开发测试联调
• WithRefreshInterval(d time.Duration): 设置SDK在后台异步更新文案的间隔时间，允许间隔为 1秒 到 1分钟，默认 10秒
• WithCacheDuration(d time.Duration): 设置SDK本地文案缓存时长，默认6小时，须大于1分钟

使用实例：

import (
	"context"
	i18ngo "github.com/volcengine/i18n-sdk-golang"
)

client := i18ngo.NewClient(
	context.Background(),
    "${YOUR_PROJECT_NAME}",
    "${YOUR_NAMESPACE}",
    gostarling.WithRetryPolicy(gostarling.NewNoRetryPolicy()),
    gostarling.WithEnableFallback(true),
    gostarling.WithRefreshInterval(time.Second*30),
    gostarling.WithCacheDuration(time.Hour*12),
)