Add multilingual README documentation

README.md

@@ -0,0 +1,101 @@
+# ZBinary2CArray
+
+[简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · **English**
+
+`ZBinary2CArray` converts a binary file into a C/C++ array. It provides a
+header-only C++20 library and a command-line program (`zbtca-cli`) for
+generating ready-to-include source files.
+
+## Features
+
+- Export binary data as `unsigned char`, `unsigned short`, `unsigned int`, or
+  `unsigned long long` arrays.
+- Generate either a self-contained header or a source file with an `extern`
+  declaration header.
+- Configure storage and const specifiers, include guards, line wrapping, and
+  generated-file annotations.
+- Automatically creates missing output directories.
+
+## Requirements
+
+- A C++20-compatible compiler.
+- CMake 3.31.6 or newer to build the command-line program.
+
+## Build
+
+```sh
+cmake -S . -B build
+cmake --build build
+```
+
+The executable is written to `build/zbtca-cli` (or `build/Debug/zbtca-cli.exe`
+for common multi-configuration generators).
+
+## Command-line usage
+
+```text
+zbtca-cli <input> [options]
+```
+
+Convert `assets/logo.bin` to an includeable header:
+
+```sh
+zbtca-cli assets/logo.bin --output generated/logo.hpp --type u8 \
+  --storage inline --const constexpr
+```
+
+By default, header-only output is generated beside the input file using the
+name `<input>.hpp`; for example, `assets/logo.bin.hpp`. Use `--source` to
+generate a `.cpp` file and a companion `extern` header:
+
+```sh
+zbtca-cli assets/logo.bin --source --output generated/logo.cpp --type u32
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `-o`, `--output <path>` | Output path. Defaults to a name derived from the input. |
+| `-t`, `--type <type>` | Element type: `u8`, `u16`, `u32`, or `u64`; defaults to `u8`. |
+| `--header-only` | Generate a header-only output file (default). |
+| `--source` | Generate a source file and an `extern` declaration header. |
+| `--no-inc-guard` | Do not emit an include guard. |
+| `--storage <spec>` | Storage specifier: `none`, `static`, or `inline`. |
+| `--const <spec>` | Const specifier: `none`, `const`, or `constexpr`. |
+| `-n`, `--nums-per-line <n>` | Elements per line; `0` selects the type-specific default. |
+| `--no-tidy` | Disable formatted hexadecimal output. |
+| `--no-anno-tool`, `--no-anno-runner`, `--no-anno-file`, `--no-anno-size`, `--no-anno-time` | Disable the corresponding generated-file annotation. |
+| `--tool-name <name>` | Override the tool name in annotations. |
+| `--runner-name <name>` | Override the runner name in annotations. |
+| `-h`, `--help` | Print command help. |
+
+## Library usage
+
+Include `ZBinary2CArray/zbtca.h`, load a binary file with `ZBTCA_Bin`, and
+write it through `ZBTCA_Output`:
+
+```cpp
+#include "ZBinary2CArray/zbtca.h"
+
+int main() {
+    ZBTCA_Bin binary("assets/logo.bin");
+    ZBTCA_Output output(binary);
+
+    auto& config = output.Config();
+    config.ExportTypeFlags = ZBTCA_Types::TypeFlags::u8;
+    config.HeaderOnly = true;
+    config.StorageSpecifier = ZBTCA_Types::OutputCfg::StorageSpecifier_inline;
+    config.ConstSpecifier = ZBTCA_Types::OutputCfg::ConstSpecifier_constexpr;
+
+    const ZBTCA_Response response = output("generated/logo.hpp");
+    return response.status() ? 0 : 1;
+}
+```
+
+The generated identifier is derived from the input filename; characters that
+are invalid in C/C++ identifiers are replaced with underscores.
+
+## License
+
+This project is released under the [MIT License](LICENSE).

README.zh-CN.md

@@ -0,0 +1,97 @@
+# ZBinary2CArray
+
+**简体中文** · [繁體中文](README.zh-TW.md) · [English](README.md)
+
+`ZBinary2CArray` 用于将二进制文件转换为 C/C++ 数组。项目提供仅头文件的
+C++20 库，以及可生成可直接包含源码文件的命令行程序 `zbtca-cli`。
+
+## 特性
+
+- 支持导出为 `unsigned char`、`unsigned short`、`unsigned int` 或
+  `unsigned long long` 数组。
+- 可生成独立头文件，或生成源文件及带有 `extern` 声明的配套头文件。
+- 可配置存储说明符、常量说明符、包含保护、换行数量和生成文件注释。
+- 自动创建不存在的输出目录。
+
+## 环境要求
+
+- 支持 C++20 的编译器。
+- 构建命令行程序需要 CMake 3.31.6 或更高版本。
+
+## 构建
+
+```sh
+cmake -S . -B build
+cmake --build build
+```
+
+可执行文件位于 `build/zbtca-cli`；使用常见多配置生成器时，通常位于
+`build/Debug/zbtca-cli.exe`。
+
+## 命令行用法
+
+```text
+zbtca-cli <input> [options]
+```
+
+将 `assets/logo.bin` 转换为可包含的头文件：
+
+```sh
+zbtca-cli assets/logo.bin --output generated/logo.hpp --type u8 \
+  --storage inline --const constexpr
+```
+
+默认会在输入文件旁生成仅头文件输出，文件名为 `<input>.hpp`，例如
+`assets/logo.bin.hpp`。使用 `--source` 可生成 `.cpp` 文件及配套的 `extern`
+声明头文件：
+
+```sh
+zbtca-cli assets/logo.bin --source --output generated/logo.cpp --type u32
+```
+
+### 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `-o`, `--output <path>` | 输出路径；默认根据输入路径生成。 |
+| `-t`, `--type <type>` | 元素类型：`u8`、`u16`、`u32` 或 `u64`；默认 `u8`。 |
+| `--header-only` | 生成仅头文件输出（默认）。 |
+| `--source` | 生成源文件及含 `extern` 声明的头文件。 |
+| `--no-inc-guard` | 不生成包含保护。 |
+| `--storage <spec>` | 存储说明符：`none`、`static` 或 `inline`。 |
+| `--const <spec>` | 常量说明符：`none`、`const` 或 `constexpr`。 |
+| `-n`, `--nums-per-line <n>` | 每行元素数；`0` 使用按类型设定的默认值。 |
+| `--no-tidy` | 禁用格式化的十六进制输出。 |
+| `--no-anno-tool`、`--no-anno-runner`、`--no-anno-file`、`--no-anno-size`、`--no-anno-time` | 禁用对应的生成文件注释。 |
+| `--tool-name <name>` | 覆盖注释中的工具名称。 |
+| `--runner-name <name>` | 覆盖注释中的运行者名称。 |
+| `-h`, `--help` | 显示命令帮助。 |
+
+## 库用法
+
+包含 `ZBinary2CArray/zbtca.h`，使用 `ZBTCA_Bin` 读取二进制文件，再通过
+`ZBTCA_Output` 写出：
+
+```cpp
+#include "ZBinary2CArray/zbtca.h"
+
+int main() {
+    ZBTCA_Bin binary("assets/logo.bin");
+    ZBTCA_Output output(binary);
+
+    auto& config = output.Config();
+    config.ExportTypeFlags = ZBTCA_Types::TypeFlags::u8;
+    config.HeaderOnly = true;
+    config.StorageSpecifier = ZBTCA_Types::OutputCfg::StorageSpecifier_inline;
+    config.ConstSpecifier = ZBTCA_Types::OutputCfg::ConstSpecifier_constexpr;
+
+    const ZBTCA_Response response = output("generated/logo.hpp");
+    return response.status() ? 0 : 1;
+}
+```
+
+生成的标识符由输入文件名派生；不符合 C/C++ 标识符规则的字符会被替换为下划线。
+
+## 许可证
+
+本项目采用 [MIT 许可证](LICENSE)。

README.zh-TW.md

@@ -0,0 +1,97 @@
+# ZBinary2CArray
+
+[简体中文](README.zh-CN.md) · **繁體中文** · [English](README.md)
+
+`ZBinary2CArray` 可將二進位檔案轉換為 C/C++ 陣列。專案提供僅標頭檔的
+C++20 函式庫，以及能產生可直接包含之原始碼檔案的命令列程式 `zbtca-cli`。
+
+## 功能
+
+- 支援匯出為 `unsigned char`、`unsigned short`、`unsigned int` 或
+  `unsigned long long` 陣列。
+- 可產生獨立標頭檔，或產生原始碼檔及附帶 `extern` 宣告的標頭檔。
+- 可設定儲存說明符、常數說明符、包含保護、每行元素數量與產生檔案註解。
+- 自動建立不存在的輸出目錄。
+
+## 環境需求
+
+- 支援 C++20 的編譯器。
+- 建置命令列程式需要 CMake 3.31.6 或更新版本。
+
+## 建置
+
+```sh
+cmake -S . -B build
+cmake --build build
+```
+
+執行檔位於 `build/zbtca-cli`；使用常見多組態產生器時，通常位於
+`build/Debug/zbtca-cli.exe`。
+
+## 命令列用法
+
+```text
+zbtca-cli <input> [options]
+```
+
+將 `assets/logo.bin` 轉換為可包含的標頭檔：
+
+```sh
+zbtca-cli assets/logo.bin --output generated/logo.hpp --type u8 \
+  --storage inline --const constexpr
+```
+
+預設會在輸入檔案旁產生僅標頭檔輸出，檔名為 `<input>.hpp`，例如
+`assets/logo.bin.hpp`。使用 `--source` 可產生 `.cpp` 檔案與附帶的 `extern`
+宣告標頭檔：
+
+```sh
+zbtca-cli assets/logo.bin --source --output generated/logo.cpp --type u32
+```
+
+### 選項
+
+| 選項 | 說明 |
+| --- | --- |
+| `-o`, `--output <path>` | 輸出路徑；預設依輸入路徑產生。 |
+| `-t`, `--type <type>` | 元素類型：`u8`、`u16`、`u32` 或 `u64`；預設為 `u8`。 |
+| `--header-only` | 產生僅標頭檔輸出（預設）。 |
+| `--source` | 產生原始碼檔及含 `extern` 宣告的標頭檔。 |
+| `--no-inc-guard` | 不產生包含保護。 |
+| `--storage <spec>` | 儲存說明符：`none`、`static` 或 `inline`。 |
+| `--const <spec>` | 常數說明符：`none`、`const` 或 `constexpr`。 |
+| `-n`, `--nums-per-line <n>` | 每行元素數；`0` 使用依類型設定的預設值。 |
+| `--no-tidy` | 停用格式化的十六進位輸出。 |
+| `--no-anno-tool`、`--no-anno-runner`、`--no-anno-file`、`--no-anno-size`、`--no-anno-time` | 停用對應的產生檔案註解。 |
+| `--tool-name <name>` | 覆寫註解中的工具名稱。 |
+| `--runner-name <name>` | 覆寫註解中的執行者名稱。 |
+| `-h`, `--help` | 顯示命令說明。 |
+
+## 函式庫用法
+
+包含 `ZBinary2CArray/zbtca.h`，使用 `ZBTCA_Bin` 讀取二進位檔案，再透過
+`ZBTCA_Output` 寫出：
+
+```cpp
+#include "ZBinary2CArray/zbtca.h"
+
+int main() {
+    ZBTCA_Bin binary("assets/logo.bin");
+    ZBTCA_Output output(binary);
+
+    auto& config = output.Config();
+    config.ExportTypeFlags = ZBTCA_Types::TypeFlags::u8;
+    config.HeaderOnly = true;
+    config.StorageSpecifier = ZBTCA_Types::OutputCfg::StorageSpecifier_inline;
+    config.ConstSpecifier = ZBTCA_Types::OutputCfg::ConstSpecifier_constexpr;
+
+    const ZBTCA_Response response = output("generated/logo.hpp");
+    return response.status() ? 0 : 1;
+}
+```
+
+產生的識別字由輸入檔名衍生；不符合 C/C++ 識別字規則的字元會替換為底線。
+
+## 授權條款
+
+本專案採用 [MIT 授權條款](LICENSE)。