DOCUMENT.md

GRTools.Localization

v1.1.1

本地化工具，分为 LocalizationManager 、LocalizationComponent 以及文本解析接口 ILocalizationParser 和 资源加载接口 ILocalizationLoader

本工具依赖于 UnityEngine.SystemLanguage 枚举类型，可参考该枚举值确认语言所包含语言

目前已通过 ILocalizationParser 扩展支持三种文本格式： txt、csv、json，其中 txt 为本项目自定义的规范，如需自定义文本格式规范可通过实现该接口进行扩展

LocalizationManager 负责统一管理，切换文本，通知多语言状态

LocalizationComponent 负责对控件的自动化统一更新，目前支持Text、Text Mesh、Image 和 SpriteRenderer

ILocalizationParser 负责解析本地化文本文件

ILocalizationLoader 负责加载本地化资源

目前已添加了 Resources、AssetBundle 和 Addressable 三种本地化资源管理方式的支持，需将资源按规范存放

样例可在 GRTools/LocalizationSample 查看

工具目录

|-- GRTools.Localization 本地化核心库
	|-- Core	核心库
	|-- Base	基础支持库
|-- GRTools.Localization.Utils 提供组件工具库
|-- GRTools.Localization.Addressables Addressables 支持
|-- GRTools.Localization.TMP	TextMeshPro 支持

使用说明

资源格式

根据需求选定本地化文本文件格式，可使用项目提供的 LocalizationDefaultParser 支持的三种格式，也可实现 ILocalizationParser 自定义格式解析

资源路径

确认本地化资源加载方式，可通过实现 ILocalizationLoader 自定义资源管理方式，也可使用默认提供的三种加载器，依据规范存放、处理资源，可在下方见详细资源管理规范

初始化

代码中，使用 LocalizationManager.Init 方法初始化单例，传入使用的加载器，解析器

使用

LocalizationChangeEvent 监听语言切换事件

RefreshInfoList更换加载器解析器并重新读取语言配置列表

ChangeToLanguage 切换语言

GetLocalizedText获取本地化文本字段

若配合 LocalizationComponent 使用，文件中值可为本地化文案，也可为本地化图片路径（Resources 下路径）

LocalizationManager

• LocalizationChangeEvent

  本地化语言更改事件

• InfoList

  本地化资源配置信息列表

• WarnMissedValue

  是否 Log 警告键值或图片缺失，默认false，随时开关

• CurrentLanguage

  当前语言名，依据 UnityEngine.SystemLanguage 枚举值名称

• CurrentLanguageIndex

  当前语言在 FileList 中 Index

• SystemLanguage

  系统语言，由 Application.systemLanguage 转换成 string

• CurrentLocalizationInfo

  当前选择语言文件

• Init(ILocalizationLoader assetLoader, ILocalizationParser assetParser, bool followSystem = true, SystemLanguage defaultLanguage = SystemLanguage.English)

  必须调用，否则无法生成单例，默认开启跟随系统语言 (followSystem)，默认使用英语

• RefreshInfoList(ILocalizationLoader assetLoader = null, ILocalizationParser assetParser = null, Action completed = null)

• ClearLanguageSelection()

  清除语言选择记录

• ChangeToLanguage(int index, Action success) / ChangeToLanguage(SystemLanguage language, Action success)

  根据 FileList index 或 SystemLanguage 更改语言，返回是否成功

• GetLocalizedText(string key, string defaultText = "")

  由键获取文案或相应的资源路径，可设置默认文本

LocalizationExtensions

• Init(bool followSystem = true, SystemLanguage defaultLanguage = SystemLanguage.English)

  使用默认LocalizationResourcesLoader加载器和 LocalizationDefaultParser 解析器

• Init(ILocalizationLoader assetLoader, LocalizationTextType textType = LocalizationTextType.Csv, bool followSystem = true, SystemLanguage defaultLanguage = SystemLanguage.English)

  使用自定义加载器和默认解析器

• LoadLocalizationAssetAsync(string assetPath, Action callback) where TAsset : Object

  异步通过传入的资源路径获取资源

LocalizationInfo

多语言资源配置信息，用于 ILocalizationLoader 读取，可继承复写用于自定义加载器使用

• LanguageType

  语言类型

• TextAssetPath

  多语言文本文件路径

• AssetsPath

  资源文件路径

LocalizationManifest

用于保存 LocalizationInfo 列表的 ScriptableObject，配合默认加载器使用，可自定义其他配置文件

LocalizationComponentList

用于挂载 Monobehavior 对象，自动执行控件更新，可增加 LocalizationComponentItem 数组内容配置相应键值

• LocalizationComponentItem

  • component

    需更新的组件，目前支持 Text、Text Mesh、Image 与 SpriteRenderer

  • localizationKey

    本地化键，用于获取本地化文本或作为图片名获取本地化图片

  • defaultValue

    默认文本（图片名），当使用 localizationKey 获取的内容为空时，则使用 defaultValue 直接展示或获取默认图片

  • setNativeSize

    更新图片时是否使用图片原始尺寸，否则使用配置尺寸

ILocalizationLoader

本地化资源加载器接口，需实现以下两方法提供给 LocalizationManager 使用

• LoadManifestAsync(Action<bool, LocalizationInfo[]> completed)

  加载语言文本文件列表

• LoadLocalizationTextAsset(LocalizationInfo info, Action