Tera Term 帮助文档构建：SBAppLocale 解决 HTML Help 日文乱码的安装与使用全指南

本文以 Tera Term 仓库的 buildtools/install_sbapplocale.md 为骨架，结合仓库中的实际安装脚本（install_sbapplocale.bat / install_sbapplocale.cmake）与 CHM 构建流水线（doc/makechm.bat、doc/ja|en/CMakeLists.txt），系统讲解 SBAppLocale 在 Tera Term 文档构建中的作用、安装校验机制以及在 hhc.exe 编译 CHM 时的真实调用方式。读完本文，你将掌握：为什么要为 HTML Help 编译器套一层区域设置工具、Tera Term 如何自动化下载并校验 SBAppLocale、以及 1041/1033 等 LCID 参数在日文/英文 CHM 构建中的正确用法。

为什么需要 SBAppLocale：HTML Help 的"文字化け"问题

Tera Term 的手册以 HTML 源文件维护，最终通过微软 HTML Help Workshop 的 hhc.exe 编译为 CHM 帮助文件（见 doc/makechm.bat、doc/ja/CMakeLists.txt、doc/en/CMakeLists.txt）。然而，hhc.exe 这类传统 16/32 位命令行编译工具在非英语区域环境下编译包含日文等多字节字符的工程时，容易因代码页与区域设置不匹配而产生乱码（日语称"文字化け"），导致最终 CHM 中标题、索引（.hhk）、目录（.hhc）等文本无法正确显示。

Tera Term 的官方文档 install_sbapplocale.md 明确说明：SBAppLocale 就是为"HTML help 文字化け対策"（HTML Help 乱码对策）而引入的构建期工具。其思路与业界知名开源项目一致——文档中记录，该方案参考了 WinMerge（文档标注的提交 a162a49）与 TortoiseGit 的处理方式：不修改系统区域设置，而是借助 SBAppLocale 以指定的区域设置（LCID）启动 hhc.exe，让编译器在"正确语言环境"下完成 CHM 编译，从根源上避免乱码。

说明：SBAppLocale 本身是 Steel Bytes 发布的一款轻量区域设置（Locale）启动器类工具，作用是在不更改系统默认区域设置的前提下，以指定语言/区域参数运行目标程序。本文仅依据 Tera Term 仓库内脚本的实测调用方式展开，不涉及对其发行渠道与第三方站点的介绍。

安装脚本一览：一键获取与校验 SBAppLocale

Tera Term 把 SBAppLocale 的获取做成了两个可复用文件，位于 buildtools/ 目录下：

文件	作用
install_sbapplocale.bat	Windows 批处理入口，负责找到 CMake 并调用 CMake 脚本
install_sbapplocale.cmake	核心逻辑：下载、SHA-256 校验、解压 SBAppLocale

批处理入口：install_sbapplocale.bat

echo %~dp0\install_sbapplocale.bat

pushd %~dp0

if "%CMAKE_COMMAND%" == "" (
   call ..\ci_scripts\find_cmake.bat
)
"%CMAKE_COMMAND%" -P install_sbapplocale.cmake

popd

if not "%NOPAUSE%" == "1" pause

脚本逻辑非常朴素：切换到自身所在目录（%~dp0，即 buildtools/）；若环境变量 CMAKE_COMMAND 未设置，则回退调用 ci_scripts/find_cmake.bat 自动定位 CMake；随后以 -P（脚本模式，不参与构建）执行 install_sbapplocale.cmake。NOPAUSE 环境变量用于在无人值守构建（如 CI）中跳过结尾的 pause，这一点在 doc/makechm.bat 中被显式利用（见下文）。

下载、校验与解压：install_sbapplocale.cmake

install_sbapplocale.cmake 是安装流程的核心，先定义四个关键变量：

set(SBAPPLOCALE_EXE "${CMAKE_CURRENT_LIST_DIR}/sbapplocale/sbapplocale.exe")
set(SBAPPLOCALE_EXE_HASH "bcabc2d5ab34bff8f147d12b69e0a019d16cf6c06859ba765e4e68f20c948577")
set(SBAPPLOCALE_URL "http://www.magicnotes.com/steelbytes/SBAppLocale_ENG.zip")
set(SBAPPLOCALE_ZIP "${CMAKE_CURRENT_LIST_DIR}/download/sbapplocale/SBAppLocale_ENG.zip")
set(SBAPPLOCALE_ZIP_HASH "e9edfd32cd5f03b36fac024f814ab8dd38e4880f3e6faacdea92d0e4d671fac1")

各变量含义：

• SBAPPLOCALE_EXE：解压后的可执行文件目标路径（buildtools/sbapplocale/sbapplocale.exe）；
• SBAPPLOCALE_EXE_HASH：期望的 sbapplocale.exe SHA-256 摘要，用于幂等校验；
• SBAPPLOCALE_URL：安装包下载地址（SBAppLocale_ENG.zip）；
• SBAPPLOCALE_ZIP：下载文件的本地落盘路径（buildtools/download/sbapplocale/SBAppLocale_ENG.zip）；
• SBAPPLOCALE_ZIP_HASH：期望的压缩包 SHA-256 摘要，用于下载完整性校验。

脚本的运行分为三个步骤：

第一步：已安装则校验后直接返回。 若 sbapplocale.exe 已存在，脚本计算其 SHA-256 并与 SBAPPLOCALE_EXE_HASH 比对；一致即 return()，实现"重复执行不重复下载"的幂等行为；不一致则打印实际/期望哈希，继续走下载流程覆盖修复。

第二步：下载。 使用 CMake 内置的 file(DOWNLOAD ...) 指令，配合 EXPECTED_HASH SHA256=${SBAPPLOCALE_ZIP_HASH} 对压缩包做校验，SHOW_PROGRESS 输出进度：

file(MAKE_DIRECTORY "${CMAKE_CURRENT_LIST_DIR}/download/sbapplocale")
file(DOWNLOAD
  ${SBAPPLOCALE_URL}
  ${SBAPPLOCALE_ZIP}
  EXPECTED_HASH SHA256=${SBAPPLOCALE_ZIP_HASH}
  SHOW_PROGRESS
)

第三步：解压。 先递归删除旧目录 buildtools/sbapplocale，再重建并以 file(ARCHIVE_EXTRACT ...) 解压 ZIP：

if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/sbapplocale")
  file(REMOVE_RECURSE "${CMAKE_CURRENT_LIST_DIR}/sbapplocale")
endif()
file(MAKE_DIRECTORY "${CMAKE_CURRENT_LIST_DIR}/sbapplocale")
file(ARCHIVE_EXTRACT
  INPUT ${SBAPPLOCALE_ZIP}
  DESTINATION "${CMAKE_CURRENT_LIST_DIR}/sbapplocale"
)

值得强调的安全设计：下载与落地两个环节都绑定了 SHA-256 期望值。即便下载源被劫持或文件传输损坏，哈希不匹配也会使构建失败，从而阻断不可信二进制进入构建链。这层防护在 install_sbapplocale.cmake 的变量定义中一目了然。

在 CHM 构建中的真实调用：makechm.bat 与 LCID 参数

SBAppLocale 并非孤立安装，它的用武之地在 CHM 编译阶段。仓库中的 doc/makechm.bat 给出了完整而清晰的调用范例：

setlocal

set NOPAUSE=1
call ..\buildtools\install_sbapplocale.bat

if exist "%Programfiles(x86)%\HTML Help Workshop\hhc.exe" (
    set HELP_COMPILER="%Programfiles(x86)%\HTML Help Workshop\hhc.exe"
) else (
    set HELP_COMPILER=C:\progra~1\htmlhe~1\hhc.exe
)

REM for winxp installation on other drive or other language
if exist "%Programfiles%\HTML Help Workshop\hhc.exe" (
    set HELP_COMPILER="%Programfiles%\HTML Help Workshop\hhc.exe"
)

set SBAppLocale=..\buildtools\SBAppLocale\SBAppLocale.exe

CALL convtext.bat

:JA
for /f "delims=" %%i in ('perl htmlhelp_update_check.pl ja teratermj.chm') do @set updated=%%i
if "%updated%"=="updated" (
    perl htmlhelp_index_make.pl ja html -o ja\Index.hhk
    %SBAppLocale% 1041 %HELP_COMPILER% ja\teraterm.hhp
)

:English
for /f "delims=" %%i in ('perl htmlhelp_update_check.pl en teraterm.chm') do @set updated=%%i
if "%updated%"=="updated" (
    perl htmlhelp_index_make.pl en html -o en\Index.hhk
    %SBAppLocale% 1033 %HELP_COMPILER% en\teraterm.hhp
)

endlocal

这段脚本揭示的调用要点：

1. 先装后编：第 4 行以 NOPAUSE=1 静默调用 ..\buildtools\install_sbapplocale.bat，确保 SBAppLocale 就绪后再进入编译流程——这正是前文"安装脚本"被消费的实际入口。

2. 编译器定位：依次探测 %Programfiles(x86)%\HTML Help Workshop\hhc.exe、8.3 短路径 C:\progra~1\htmlhe~1\hhc.exe，并保留了对旧版 Windows/非默认安装盘的兼容分支。

3. LCID 参数是核心：

   • %SBAppLocale% 1041 %HELP_COMPILER% ja\teraterm.hhp：以 1041（日语 LCID） 启动 hhc.exe 编译日文工程 teraterm.hhp；
   • %SBAppLocale% 1033 %HELP_COMPILER% en\teraterm.hhp：以 1033（英语-美国 LCID） 启动 hhc.exe 编译英文工程。

   也就是说，hhc.exe 自身参数不变，只是被 SBAppLocale"包裹"，在指定的区域设置中执行。这样日文标题、索引字符便能按日文代码页正确处理，规避乱码。

4. 增量编译：调用 perl htmlhelp_update_check.pl ja|en <chm文件名> 判断 HTML 帮助源是否更新（通过比较源文件与既有 CHM 的修改时间，详见 doc/htmlhelp_update_check.pl），仅在 updated 时重新生成索引（doc/htmlhelp_index_make.pl 生成 Index.hhk）并重新编译，避免无谓的重建。

补充说明：makechm.bat 中以 ..\buildtools\SBAppLocale\SBAppLocale.exe 引用工具，而 CMake 脚本生成的是小写目录 buildtools/sbapplocale/sbapplocale.exe。Windows 文件系统默认不区分大小写，因此两者可互通；这也说明整个流程强依赖 Windows 环境。

SBAppLocale 与 CMake 构建链的分工

除了批处理路径，Tera Term 还提供了基于 CMake 的 CHM 构建目标（doc/CMakeLists.txt → doc/ja/CMakeLists.txt、doc/en/CMakeLists.txt）：

• doc/CMakeLists.txt 在 CMAKE_HOST_WIN32 下通过 find_program(HHC hhc.exe ...) 定位 HTML Help Workshop 编译器，并兼容跨平台的开源 chmcmd 编译器；
• doc/ja/CMakeLists.txt 与 doc/en/CMakeLists.txt 通过 add_custom_command 生成 teratermj.chm / teraterm.chm：先由 htmlhelp_index_make.pl 生成 Index.hhk，再调用 doc/chm.cmake 执行 hhc teraterm.hhp，最后把产物移动到二进制目录并 install。

可以看到，仓库中存在两条并行构建路径：批处理路径（makechm.bat）显式套用 SBAppLocale + LCID 参数来规避乱码；CMake 路径则直接驱动 hhc/chmcmd（doc/chm.cmake 中不包含 SBAppLocale 包装，这从 doc/ja/CMakeLists.txt 的 COMMAND ${CMAKE_COMMAND} -DHHC=${HHC_COMMAND} -P ../chm.cmake 可以推断）。日常手工构建日文 CHM 时，优先走 doc/makechm.bat 可获得完整的区域设置保护。

使用前提与注意事项

综合 install_sbapplocale.cmake、install_sbapplocale.bat 与 doc/makechm.bat 的实现，实际使用需要注意以下前提与边界：

1. 运行环境：必须在 Windows 上执行（脚本依赖 %~dp0、pushd、%Programfiles% 及大小写不敏感的文件系统）；CMake 脚本中的 CMAKE_HOST_WIN32 判断也印证了这一点（doc/CMakeLists.txt）。
2. 前置依赖：批处理会自动寻找 ci_scripts/find_cmake.bat；完整 CHM 构建还需要 Perl（htmlhelp_update_check.pl、htmlhelp_index_make.pl、convtext.bat 的转换脚本）与 HTML Help Workshop 的 hhc.exe（或替代编译器 chmcmd）。
3. 网络与校验：首次运行需要联网下载 SBAppLocale_ENG.zip，下载与解压后的 exe 均受 SHA-256 校验约束；一旦官方发布新版本导致哈希变化，脚本会打印 actual HASH=... 与 expect HASH=... 并重新下载，此时需同步更新脚本中的哈希常量才能通过校验。
4. 幂等与可重入：sbapplocale.exe 哈希一致时脚本直接返回，重复构建不会重复下载；makechm.bat 中的 htmlhelp_update_check.pl 又保证了仅当帮助源更新时才触发重编译，适合反复迭代文档的日常场景。
5. 仓库只读：以上工具目录（buildtools/sbapplocale/、buildtools/download/sbapplocale/）属于构建期产物，仅用于本地构建环境的搭建与运行，不应对仓库源文件做任何修改。

小结

SBAppLocale 在 Tera Term 中承担的是一个"小而关键"的角色：它以 LCID 参数包装 hhc.exe，为日文/英文 CHM 编译提供正确的区域设置，根治 HTML Help 编译乱码；而 install_sbapplocale.cmake 通过"哈希校验 + 幂等安装 + 自动解压"把第三方工具的引入做成了可审计、可重复、可无人值守的构建步骤。理解这条从 install_sbapplocale.bat 到 makechm.bat 的完整链路，对于维护 Tera Term 多语言文档构建、排查 CHM 乱码问题，或在自己项目中引入"区域设置包装编译"方案，都具有直接的参考价值。