如何设置 CLI 并扫描我的项目？

Better i18n CLI 是一个开发者工具，用于扫描代码库中的翻译键并与控制台保持同步。

安装

# 使用 bun（推荐）
bun add -g @better-i18n/cli

# 使用 npm
npm install -g @better-i18n/cli

# 使用 pnpm
pnpm add -g @better-i18n/cli

验证安装：

better-i18n --version

身份验证

用您的 Better i18n 账号登录：

better-i18n login

这将打开浏览器进行身份验证。您的凭据会安全地存储在本地。

项目配置

在项目根目录创建配置文件：

better-i18n init

这将生成 better-i18n.config.ts：

import { defineConfig } from '@better-i18n/cli';

export default defineConfig({
  project: 'acme/dashboard',
  sourceLocale: 'en',
  // 扫描翻译键的目录
  include: ['src/**/*.{ts,tsx,js,jsx}'],
  // 排除的目录
  exclude: ['node_modules', 'dist', '.next'],
});

扫描代码库

运行扫描器查找所有翻译键：

better-i18n scan

扫描器可以识别：

• t('key') — 标准翻译函数调用
• t('namespace:key') — 带命名空间的键
• useTranslations('namespace') — 命名空间导入
• 模板字面量：t(`key.${dynamic}`)（报告为动态键）

扫描输出

Scanning src/**/*.{ts,tsx}...

 Found 142 translation keys in 38 files
   • common: 24 keys
   • auth: 18 keys
   • dashboard: 45 keys
   • settings: 32 keys
   • (default): 23 keys

 ⚠ 3 dynamic keys detected (review manually)

同步到控制台

将扫描到的键推送到 Better i18n：

better-i18n sync

这将：

1. 将本地键与控制台进行比较
2. 创建尚不存在的新键
3. 报告控制台中存在但代码中不存在的键（潜在的废弃键）

检查同步状态

验证所有内容是否已同步：

better-i18n check

✓ 142 keys in sync
⚠ 3 keys in code but not in dashboard (run sync to fix)
⚠ 5 keys in dashboard but not in code (potential dead keys)

运行 doctor

诊断常见问题：

better-i18n doctor

这将检查您的配置、身份验证、API 连接性和项目设置。

CI/CD 集成

将 better-i18n check 添加到 CI 流水线，以在合并前捕获缺失的翻译：

# GitHub Actions 示例
- name: Check translations
  run: better-i18n check --strict

--strict 标志在任何键不同步时以代码 1 退出。

下一步

• 设置 Next.js SDK
• 添加您的第一批翻译键