# AndroidStringTransformer

**Repository Path**: 91915250/android-string-transformer

## Basic Information

- **Project Name**: AndroidStringTransformer
- **Description**: android 字符文件转换工具，多语言 string.xml 转换为 excel ,excel 更新xml
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-16
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Android 字符串资源转换工具

## 📋 工具简介

本工具实现 Android APP 多语言字符串资源的双向转换：
- **XML → Excel**：提取多个 APP 的 `strings.xml` 到 Excel（按 APP 分 sheet）
- **Excel → XML**：从 Excel 更新回 `strings.xml` 文件

**系统要求**：Windows 7/10/11，Python 3.6+（推荐 3.8+）

---

## 🚀 快速开始

### 1. 安装依赖

```bash
python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2. 配置文件

创建 `config.json`：

```json
{
  "apps": [
    {
      "app_name": "TestApp",
      "xml_files": [
        {
          "name": "English",
          "path": "H:/path/to/app/res/values/strings.xml"
        },
        {
          "name": "俄语",
          "path": "H:/path/to/app/res/values-ru/strings.xml"
        }
      ]
    }
  ],
  "output": {
    "output_file": "./strings_output.xlsx"
  }
}
```

### 3. 执行转换

**提取 XML 到 Excel**：
```bash
python xml_to_excel_extract.py
```

**从 Excel 更新 XML**：
```bash
python excel_to_xml_generate.py
```

---

## ✅ 输出示例

### Excel → XML 成功输出示例

```
处理 App: TestApp
  找到列: ['String Name', 'English', '俄语']
  处理列: English -> H:/path/to/app/res/values/strings.xml
  现有字符串数量: 25
  Excel 中不为空的行数: 25
  合并后的字符串数量: 25
  统计: 更新 0 条, 跳过 25 条, 错误 0 条
  成功更新: H:/path/to/app/res/values/strings.xml

============================================================
统计信息:
============================================================

【全部跳过（无更新无错误）】
App 'TestApp':
  - 列 'English': 25 条
  - 列 '俄语': 25 条

✓ 没有错误

完成: 所有已完成并全部更新总数 50 条
```

### Excel → XML 有更新时的输出

```
============================================================
统计信息:
============================================================

【全部跳过（无更新无错误）】
App 'TestApp':
  - 列 'English': 20 条

【有更新或错误】
App 'TestApp':
  列 '俄语': 总数 25 条 - 更新 5 条

✓ 没有错误

完成: 所有已完成并全部更新总数 45 条
```

### Excel → XML 有错误时的输出

```
============================================================
统计信息:
============================================================

【全部跳过（无更新无错误）】
App 'TestApp':
  - 列 'English': 25 条

【有更新或错误】
App 'TestApp':
  列 '俄语': 总数 10 条 - 错误 1 条（路径为空或错误，请检查）

============================================================
错误汇总:
============================================================
  - App 'TestApp' 列 '俄语': 路径为空，已跳过 XML 写入

完成: 更新 0 条，错误 1 条
```

### XML → Excel 成功输出示例

```
处理 App: TestApp
  找到列: ['String Name', 'English', '俄语']
  处理列: English -> H:/path/to/app/res/values/strings.xml
  解析 XML: English -> 25 个字符串
  处理列: 俄语 -> H:/path/to/app/res/values-ru/strings.xml
  解析 XML: 俄语 -> 25 个字符串
完成处理: TestApp

统计信息:
App 'TestApp':
  - 成功: 2 个 XML 文件
  - 跳过: 0 个（路径为空等）
  - 错误: 0 个

✓ 没有错误

成功: 数据已保存到 strings_output.xlsx
```

## ✅ 成功判断标准

**Excel → XML（excel_to_xml_generate.py）**：
- ✅ **成功**：显示 "✓ 没有错误" 且错误汇总为空
- ⚠️ **需要检查**：如果显示 "【有更新或错误】" 部分，请查看：
  - **路径错误**：显示 "路径为空或错误，请检查" → 需要检查配置文件中的路径是否正确
  - **有更新**：显示 "更新 X 条" → 正常，表示已成功更新
  - **有错误**：查看错误汇总，修复后重试

**XML → Excel（xml_to_excel_extract.py）**：
- ✅ **成功**：显示 "成功: 数据已保存到..." 且错误汇总为空
- ❌ **失败**：显示 "失败: 数据未成功保存..." 或有错误汇总

## ⚠️ 需要检查的情况

1. **路径错误**：统计信息中显示 "路径为空或错误，请检查"
   - 检查 `config.json` 中该列的 `path` 字段是否正确
   - 如果该语言尚未翻译，路径可以为空字符串 `""`（这是正常的）

2. **错误汇总不为空**：查看错误汇总部分，根据错误信息修复：
   - 路径不存在 → 检查路径是否正确
   - 文件不存在 → 检查文件是否存在
   - 权限错误 → 检查文件权限

3. **空列跳过**：如果显示 "跳过空列: xxx（所有值都为空）"
   - 这是正常的，表示该列在 Excel 中所有值都为空，不需要更新

---

## ⚙️ 配置文件说明

### 基本结构

```json
{
  "apps": [
    {
      "app_name": "APP名称",     // ⚠️ 必须与 Excel sheet 名称一致
      "xml_files": [
        {
          "name": "列名",        // ⚠️ 必须与 Excel 列名一致
          "path": "XML文件路径"  // 可以为空字符串 ""
        }
      ]
    }
  ],
  "output": {
    "output_file": "输出Excel路径"
  }
}
```

### ⚠️ 重要提示

1. **Excel → XML 时**：
   - Excel 的 **sheet 名称** 必须与 `app_name` 完全一致
   - Excel 的 **列名** 必须与 `name` 字段完全一致
   - 第一列必须是 `String Name`

2. **路径格式**：
   - 支持正斜杠 `/` 和反斜杠 `\`，会自动规范化
   - 支持绝对路径和相对路径

3. **空路径**：
   - 如果某个语言尚未翻译，`path` 可以设置为空字符串 `""`
   - XML → Excel：会创建空列
   - Excel → XML：会跳过写入并显示警告

---

## ❓ 常见问题

### 1. Excel sheet 名称不匹配

**错误**：`警告: 跳过未在配置中找到的 sheet: SheetName`

**解决**：确保 Excel 中的 sheet 名称与 `config.json` 中的 `app_name` 完全一致（包括大小写）

### 2. Excel 列名不匹配

**错误**：`警告: 列 '列名' 在配置中找不到对应的 XML 文件路径，跳过`

**解决**：确保 Excel 中的列名与 `config.json` 中的 `name` 字段完全一致

### 3. 文件被占用

**错误**：`输出文件被其他程序占用，无法删除`

**解决**：关闭 Excel 或其他正在使用该文件的程序

### 4. 路径不存在

**错误**：`XML 文件不存在: path/to/file.xml`

**解决**：检查路径是否正确，文件是否存在

### 5. 配置文件格式错误

**错误**：`配置文件格式验证失败`

**解决**：检查 JSON 格式，确保所有必需字段都存在（参考上面的配置示例）

---

## 📚 详细文档

更多详细说明、配置示例、故障排查等，请查看：[README_DETAILED.md](README_DETAILED.md)

---

## 📝 注意事项

1. 执行 Excel → XML 前，建议备份原始 XML 文件
2. 工具采用智能更新：只更新有变化且非空的值
3. 如果 XML 文件不存在，会自动创建
4. 如果输出 Excel 文件已存在，会自动删除并重新创建