# multy-languages-script **Repository Path**: feer/multy-languages-script ## Basic Information - **Project Name**: multy-languages-script - **Description**: Android 对多语言文档自动生成Android所需要各语种strings.xml的脚本 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-16 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Android 多语言资源工具 使用 Python 3.9 或更高版本,无需安装第三方依赖。 - `xlsx_to_android.py`:从 Excel 生成 Android 多语言资源。 - `merge_android_strings.py`:将已有 Android 多语言资源按语种合并到目标目录。 ## 合并已有 Android 多语言资源 将 `android-res` 下每个语种(仅限 `android-target` 中已存在的语种目录)的 `strings.xml` 内容追加到 `android-target` 对应文件的 `` 内,并在本次追加内容前插入版本注释: ```bash python3 merge_android_strings.py android-res -o android-target --comment "V3.0" ``` 也接受完整 XML 注释,两种写法效果相同: ```bash python3 merge_android_strings.py android-res -o android-target --comment '' ``` 默认源目录为 `android-res`、目标目录为 `android-target`,均相对于当前运行目录。因此也可以直接运行: ```bash python3 merge_android_strings.py --comment "V3.0" ``` 不需要注释时省略 `--comment`。操作真实项目之前,可先预览统计并校验全部 XML,预览不会写入文件: ```bash python3 merge_android_strings.py android-res -o android-target --comment "V3.0" --dry-run ``` 合并规则: - 按相同的 `values`、`values-*` 目录名匹配,包括 `values-zh-rCN`、`values-b+zh+Hant+TW` 等。仅处理其中的 `strings.xml`,其他文件和目标独有的语种目录不变。 - **不新增语种目录**:只有目标中已存在的 `values`/`values-*` 目录才会合并;目标缺少对应语种目录时整组跳过,不创建目录。若目录存在但 `strings.xml` 缺失,则在该目录内创建文件。 - 已有目标资源保留在前,源文件 `` 内的内容追加在后。 - **重复 key 以源文件为准**:先删除目标中的同名旧资源,再追加源资源,不会保留两个重复 key。源文件自身同名时只保留最后一项,并保持保留项的原始顺序。 - 按资源类型和 `name` 去重。`` 与 `` 视为同一 key;`string-array`、`integer-array` 和 `array` 统一按数组去重。不同类型的同名资源(如 string 与 plurals)互不覆盖;数组/复数中的子 item 随整个资源一起替换。 - 保留资源原始文本,包括 CDATA、富文本、字符实体、属性、注释和 Android 转义;不再次转换占位符。保留目标根标签属性,并补全源根标签上的命名空间声明(如 `xmlns:xliff`);同名前缀定义冲突时中止并报错。 - `--comment` 仅接受一行合法 XML 注释,空内容等同不添加。源文件内容为空时,已有目标不变,也不追加版本注释。 - 支持 UTF-8(含 BOM)文件和自闭合 ``;不接受 DTD。目标资源根目录必须已存在,源、目标目录不能相同或互相包含;语种目录及 `strings.xml` 不接受符号链接。 - 按语种逐文件处理,使用哈希索引去重,内存主要取决于当前语种文件大小。先在目标同一文件系统暂存,所有源、目标和合并后的 XML 校验成功后,再逐文件原子替换对应文件,并保留已有文件权限。校验错误不会修改目标文件;写入阶段发生磁盘/权限错误或中断时,此前已替换的语种不会自动回滚。 - 源目录不会修改。重复运行仍以最新源值为准;指定注释时,每次有内容追加都会插入本次注释,已有历史注释保留。 例如,目标原有 `keep=保留`、`title=旧标题`,源有 `title=新标题`、`new_key=新增`,合并后为: ```xml 保留 新标题 新增 ``` 查看全部参数:`python3 merge_android_strings.py --help`。 ## 从 Excel 生成 Android 资源 在本目录运行: ```bash python3 xlsx_to_android.py "多语言文档.xlsx" -o android-res ``` 也可以指定任意输入文件和 Android 项目的资源目录: ```bash python3 xlsx_to_android.py "/path/to/translations.xlsx" -o "/path/to/app/src/main/res" ``` 输出示例: ```text android-res/ ├── values-zh/strings.xml ├── values-en/strings.xml ├── values-ja/strings.xml └── ... ``` 例如,key 为 `analysis_improve`、zh 列为 `分析与提升`,则在 `values-zh/strings.xml` 中生成: ```xml 分析与提升 ``` ## 读取规则 - 按工作簿标签从左到右的顺序,处理最左侧可见的 sheet,跳过隐藏表和深度隐藏表。不会按 sheetId 排序,也不会改用当前选中的表;其余 sheet、图片及格式忽略。 - 自动寻找 `key` 表头,忽略大小写及两端空白,key 左侧的说明列不导出。 - 支持语言代码与 key 在同一行,也支持代码在 key 上方的多行表头。自动选取 key 紧邻右列中最近的语言代码行,再按该行的实际列位置读取语言,空表头列跳过。 - 当前示例文件的 key 在 G3,语言代码在 H2:W2,第三行的中文语种名称不会当成代码。 - `zh` → `values-zh`,`en` / `b+en` → `values-en`;`zh-CN` / `zh_CN` / `zh-rCN` / `b+zh+CN` → `values-zh-rCN`;`zh-Hant-TW` → `values-b+zh+Hant+TW`。也支持直接填写 `b+zh+Hant+TW`。等价写法会统一目录名,以检测配置冲突;显式文字代码(如 Hant)保留。 - key 去除两端空白后原样作为 `name`,须以英文字母或下划线开头,后续只允许英文字母、数字、下划线和点。不同 key 生成相同 R 字段、Java 保留标识符(如 `class`、`true`、单独的 `_`)或重复语言目录会报错,并标明位置。 - 相同 key 只保留第一次出现的记录,以该行的各语言译文为准,后续重复行整行跳过。key 两端空白不影响去重,大小写仍有区别;运行结果会统计跳过的重复行数。 - 没有 key 的行跳过,不推测或补写 key。空译文默认跳过,数字 `0` 和仅含空格的文本保留。每个已识别的语言都会生成目录,即使该语言暂时没有译文。 - 保持源行顺序。支持普通文本、富文本的可见文字、数值和已有缓存结果的公式;不执行公式。相关单元格有 Excel 错误或公式缺少缓存时会报错。 ## 空译文和默认语言 若需要为空译文生成 ``: ```bash python3 xlsx_to_android.py "多语言文档.xlsx" -o android-res --keep-empty ``` 若需要同时生成 Android 默认资源 `values/strings.xml`,指定已有语言列: ```bash python3 xlsx_to_android.py "多语言文档.xlsx" -o android-res --default-language zh ``` 默认不额外生成 `values/`。接入 Android 项目时,应保留项目已有的默认字符串资源,或使用上面的选项生成。空翻译被跳过后可使用项目默认资源回退。[Android 官方资源目录说明](https://developer.android.com/guide/topics/resources/providing-resources#AlternativeResources) ## 文本与输出约定 - 自动将半角 `%@` 和全角百分号 `%@` 替换为 `%s`,包括 CDATA 内部的占位符。`%1$s`、`%2$d` 等已有 Android 占位符保留。 - 保留完整的 `` 区块,不把它转义成 `<![CDATA[...`。支持单元格仅包含 CDATA 或与普通文本混合,CDATA 内的 `<`、`>`、`&` 保持原样,Android 的单双引号和反斜杠仍按字符串规则处理;缺少结束标记时报错。 - 普通文本部分转义 `&`、`<`、`>` 及 Android 的单双引号、反斜杠、`@`、`?`。例如 `职业发展 & 工作` 写成 `职业发展 & 工作`,Android 显示内容不变。普通文本中的 HTML 标签作为文字转义。 - 真实换行、回车和制表符转换成 Android 的 `\n`、`\u000d`、`\t`;保留首尾空白及连续空白。单元格中原本就存在的反斜杠按字面文本保留,例如字面 `\n` 不会被猜测为换行。 - 生成的 `string` 元素仅包含 `name` 属性,按要求不自动添加 `formatted="false"`。格式参数和普通百分号按替换后的内容保留,多个 `%s` 也保持原样。文本转义参考 [Android 字符串资源说明](https://developer.android.com/guide/topics/resources/string-resource#FormattingAndStyling)。 - 输出为 UTF-8,一条 string 占 XML 中一行。非法 XML 控制字符会报错。 - 流式处理选中表的行,内存主要用于共享字符串表和已出现的 key,不加载整个工作簿或图片。 - 数据先写入临时目录,校验成功后逐文件原子替换目标目录中对应的 `strings.xml`。**同名文件会整体覆盖,不会合并已有字符串**;其他文件及本次没有生成的语言目录不变。 - 支持 `.xlsx`,不支持旧式 `.xls`。源文档不会被修改。运行 `python3 xlsx_to_android.py --help` 可查看参数。 当前示例文件保存的最左侧可见 sheet 是 `3.0.0_自适应主课系统`,`3.0.0_进阶板块(beta2)` 位于其右侧。最左侧表中只有 `career_development`、`study_abroad_exams` 两个已填写的 key,且仅 zh 有内容。因此默认生成 16 个语种目录,中文 2 条,其余语言为空 ``。补齐 key 或翻译后重新运行即可更新。若在 Excel 中调整工作表顺序,请保存文件后再运行。 CDATA 转换示例(输入内容为 `%@ & %@]]>`): ```xml %s & %s]]> ```