示例文档，国际化

Author: sfyc23

CHANGELOG.md

@@ -1,75 +1,76 @@
 # Changelog
 
-本文件记录 CountTimeProgressView 的所有重要版本变更。
+This file records notable CountTimeProgressView changes.
 
 ## [2.0.0] - 2026-04-15
 
-### Bug 修复
-- 修复 `CLOCK` 模式下 `minute >= 10` 时错误拼接 `hour` 的格式化 Bug
-- 修复 `startAngle` getter/setter 语义不一致（用户设 0 读回 270 的问题）
-- 修复 `titleCenterText` 在 SECOND 模式下的空指针崩溃风险
-- 修复 `DEFAULT_COUNT_TIME` 从 5ms 修正为 5000ms
-- 修复 Demo 中 `setBackgroundColor()` 误调用（应为 `backgroundColorCenter`）
+### Bug Fixes
+- Fixed `CLOCK` formatting when `minute >= 10` incorrectly appended `hour`
+- Fixed inconsistent `startAngle` getter/setter semantics
+- Fixed a possible `titleCenterText` null crash in SECOND mode
+- Changed `DEFAULT_COUNT_TIME` from 5ms to 5000ms
+- Fixed the demo `setBackgroundColor()` call; it now uses `backgroundColorCenter`
 
-### 新增功能
-- 暂停 / 恢复 / 重置动画：`pauseCountTimeAnimation()`、`resumeCountTimeAnimation()`、`resetCountTimeAnimation()`
-- 进度 getter/setter：`progress` 属性（0f..1f）
-- 进度变化回调：`addOnProgressChangedListener { progress, remainingMillis -> }`
-- 自定义文本格式化器：`textFormatter = { millis -> "..." }`
-- 进度条端点样式：`strokeCap`（BUTT / ROUND / SQUARE），支持 XML 配置
-- 动画插值器配置：`interpolator` 属性
-- 渐变色进度条：`gradientStartColor` / `gradientEndColor`，支持 XML 配置
-- XML 属性扩展：`autoStart`、`finishedText`、`showCenterText`、`strokeCap`
-- `onMeasure` 支持 `wrap_content`（默认尺寸 84dp）
-- SavedState 支持（屏幕旋转保持进度）
-- 无障碍支持（AccessibilityNodeInfo）
-- 显式单位 API：`setBorderWidthPx()`、`setMarkBallWidthPx()`、`setTitleCenterTextSizePx()`
-- 公开 `remainingTime` 和 `isPaused` 属性
-- Jetpack Compose 适配工具类 `CountTimeProgressViewCompose`
+### Features
+- Pause / resume / reset APIs: `pauseCountTimeAnimation()`, `resumeCountTimeAnimation()`, `resetCountTimeAnimation()`
+- `progress` getter/setter in the 0f..1f range
+- Progress callback: `addOnProgressChangedListener { progress, remainingMillis -> }`
+- Custom text formatter: `textFormatter = { millis -> "..." }`
+- Progress stroke cap: `strokeCap` (BUTT / ROUND / SQUARE), with XML support
+- Configurable animation interpolator via `interpolator`
+- Gradient progress stroke via `gradientStartColor` / `gradientEndColor`, with XML support
+- XML attributes: `autoStart`, `finishedText`, `showCenterText`, `strokeCap`
+- `wrap_content` support in `onMeasure` with an 84dp default size
+- SavedState support for restoring progress after configuration changes
+- Accessibility support via AccessibilityNodeInfo
+- Explicit pixel APIs: `setBorderWidthPx()`, `setMarkBallWidthPx()`, `setTitleCenterTextSizePx()`
+- Public `remainingTime` and `isPaused` properties
+- `CountTimeProgressViewCompose` helper for Compose AndroidView usage
 
-### 代码质量
-- 设置 `LinearInterpolator` 为默认插值器
-- 删除库中所有 `Log.e` 调用
-- 移除冗余 `mContext` 字段
-- 移除 `attr != null` 死代码分支
-- `calcRadius()` 改为 `private`
-- `TextStyle` 添加 `@IntDef` 类型安全注解
-- `OnEndListener` 标记 `@Deprecated`，新增 `OnCountdownEndListener` + `setOnClickCallback`
-- `onDetachedFromWindow` 不再清空 listener
-- 重构 `onDraw` 为多个独立绘制方法
-- 性能：文本缓存、`postInvalidateOnAnimation()` 替代 `invalidate()`
+### Code Quality
+- Set `LinearInterpolator` as the default interpolator
+- Removed all `Log.e` calls from the library
+- Removed the redundant `mContext` field
+- Removed the dead `attr != null` branch
+- Made `calcRadius()` private
+- Added `@IntDef` type safety for `TextStyle`
+- Deprecated `OnEndListener` and added `OnCountdownEndListener` + `setOnClickCallback`
+- Stopped clearing listeners in `onDetachedFromWindow`
+- Split `onDraw` into focused drawing methods
+- Improved drawing performance with text caching and `postInvalidateOnAnimation()`
 
-### 工程化
-- library 模块移除 AppCompat 运行时依赖（零第三方依赖）
-- 迁移至 AndroidX
-- `minSdk` 14 → 21，`targetSdk` / `compileSdk` → 34
-- 仓库改为 `google()` + `mavenCentral()`
-- `lintOptions {}` → `lint {}`
-- `proguard-android.txt` → `proguard-android-optimize.txt`
-- `compileSdkVersion` → `compileSdk`，`minSdkVersion` → `minSdk`
-- `artifactId` 从 `library` 改为 `counttimeprogressview`
-- SplashActivity 从 Java 转换为 Kotlin
-- 布局文件 `left/right` → `start/end`（RTL 支持）
-- ScrollView 子 View 高度改为 `wrap_content`
-- ImageView 添加 `contentDescription`
-- 移除 `gradle.properties` 中硬编码的 JDK 路径
-- 新增 `ClockTimeFormatter` 独立工具类（便于单元测试）
-- 新增 `formatClockTime` 单元测试（9 个用例）
+### Project
+- Removed AppCompat runtime dependency from the library module
+- Migrated to AndroidX
+- Raised `minSdk` from 14 to 21, and `targetSdk` / `compileSdk` to 34
+- Switched repositories to `google()` + `mavenCentral()`
+- Migrated `lintOptions {}` to `lint {}`
+- Switched to `proguard-android-optimize.txt`
+- Migrated Gradle DSL names to `compileSdk` and `minSdk`
+- Changed `artifactId` from `library` to `counttimeprogressview`
+- Converted SplashActivity from Java to Kotlin
+- Replaced `left/right` layout attributes with `start/end` for RTL support
+- Changed ScrollView child height to `wrap_content`
+- Added ImageView `contentDescription`
+- Removed the hard-coded JDK path from `gradle.properties`
+- Added the standalone `ClockTimeFormatter` utility for unit testing
+- Added 9 unit tests for `formatClockTime`
 
-### 文档
-- README / README-ZH：`compile` → `implementation`，修复中英文残片、默认值说明、拼写错误
-- 新增 CHANGELOG.md
-- 新增 CONTRIBUTING.md
-- 添加完整 KDoc 中文注释
+### Documentation
+- Updated README / README-ZH from `compile` to `implementation`
+- Fixed mixed-language snippets, default value notes, and typos
+- Added CHANGELOG.md
+- Added CONTRIBUTING.md
+- Normalized source comments and public messages to English
 
 ## [1.1.3] - 2017-11-11
-- 使用 Kotlin 重写代码
+- Rewrote the code in Kotlin
 
 ## [1.1.1] - 2017-03-27
-- 更新：退出时停止运行
+- Stopped running when exiting
 
 ## [1.1.0] - 2017-02-07
-- 更新：支持顺时针动画
+- Added clockwise animation support
 
 ## [1.0.0] - 2016-12-20
-- 首次提交
+- Initial commit

CONTRIBUTING.md

@@ -1,71 +1,71 @@
-# 贡献指南
+# Contributing Guide
 
-感谢你对 CountTimeProgressView 项目的关注！欢迎任何形式的贡献。
+Thanks for your interest in CountTimeProgressView. Contributions of all kinds are welcome.
 
-## 如何贡献
+## How to Contribute
 
-### 报告 Bug
+### Report a Bug
 
-1. 在 [Issues](https://github.com/sfyc23/CountTimeProgressView/issues) 中搜索是否已有相同问题
-2. 如果没有，创建新 Issue，请包含：
-   - 问题描述
-   - 复现步骤
-   - 期望行为 vs 实际行为
-   - 设备信息（Android 版本、设备型号）
-   - 相关代码片段或截图
+1. Search [Issues](https://github.com/sfyc23/CountTimeProgressView/issues) for an existing report.
+2. If no matching issue exists, create one and include:
+   - Problem description
+   - Steps to reproduce
+   - Expected behavior vs actual behavior
+   - Device information, including Android version and device model
+   - Relevant code snippets or screenshots
 
-### 提交代码
+### Submit Code
 
-1. Fork 本项目
-2. 创建功能分支：`git checkout -b feature/your-feature`
-3. 编写代码，确保：
-   - 遵循现有代码风格（Kotlin）
-   - 添加必要的中文注释
-   - 新增公开 API 需添加 KDoc
-   - 如有新功能，更新 README 和 CHANGELOG
-4. 运行构建验证：`./gradlew :library:assembleDebug :library:testDebugUnitTest`
-5. 提交变更：`git commit -m "feat: 你的功能描述"`
-6. 推送并创建 Pull Request
+1. Fork this repository.
+2. Create a feature branch: `git checkout -b feature/your-feature`.
+3. Make your changes and ensure:
+   - Code follows the existing Kotlin style.
+   - Comments and public messages are written in English.
+   - New public APIs include KDoc when needed.
+   - New features update README and CHANGELOG as appropriate.
+4. Run build verification: `./gradlew :library:assembleDebug :library:testDebugUnitTest`.
+5. Commit changes: `git commit -m "feat: your feature description"`.
+6. Push your branch and open a pull request.
 
-### Commit 规范
+### Commit Style
 
-建议使用以下前缀：
-- `feat:` 新功能
-- `fix:` Bug 修复
-- `docs:` 文档更新
-- `refactor:` 重构（不改变行为）
-- `perf:` 性能优化
-- `test:` 测试相关
-- `chore:` 构建/工具链变更
+Recommended prefixes:
+- `feat:` new feature
+- `fix:` bug fix
+- `docs:` documentation update
+- `refactor:` refactor without behavior changes
+- `perf:` performance improvement
+- `test:` tests
+- `chore:` build or tooling change
 
-## 开发环境
+## Development Environment
 
-- Android Studio Hedgehog 或更新版本
+- Android Studio Hedgehog or newer
 - JDK 17
 - Gradle 7.6+
 - Kotlin 1.8.22+
 
-## 项目结构
+## Project Structure
 
-```
+```text
 CountTimeProgressView/
-├── library/          # 核心库模块（零第三方依赖）
+├── library/          # Core library module with no third-party runtime dependency
 │   └── src/main/java/com/sfyc/ctpv/
-│       ├── CountTimeProgressView.kt       # 核心控件
-│       ├── CountTimeProgressViewCompose.kt # Compose 适配
-│       └── ClockTimeFormatter.kt          # 时钟格式化工具
-├── app/              # 示例 App 模块
-└── .AI/              # 重构分析文档
+│       ├── CountTimeProgressView.kt        # Core custom view
+│       ├── CountTimeProgressViewCompose.kt # Compose helper
+│       └── ClockTimeFormatter.kt           # Clock formatting utility
+├── app/              # Sample app module
+└── .AI/              # Refactor analysis notes
 ```
 
-## 编码规范
+## Coding Guidelines
 
-- 使用 Kotlin，避免 Java
-- 公开 API 添加 KDoc 注释（中文）
-- 属性 setter 中 dp/sp 转换需在注释中标明单位
-- `onDraw` 中避免创建对象
-- 新增 XML 属性需同步更新 `attrs.xml`
+- Prefer Kotlin for new code.
+- Add KDoc to public APIs when it clarifies usage.
+- Document dp/sp conversion behavior when adding public size APIs.
+- Avoid allocating objects in `onDraw`.
+- Update `attrs.xml` when adding XML attributes.
 
-## 许可证
+## License
 
-贡献的代码将遵循本项目的 [Apache License 2.0](LICENSE) 许可证。
+Contributed code follows this project's [Apache License 2.0](LICENSE).

README.md

@@ -1,16 +1,16 @@
 [![twitter](https://img.shields.io/badge/twitter-sfyc23-blue.svg)](https://twitter.com/sfyc23)
-[![微博](https://img.shields.io/badge/%E5%BE%AE%E5%8D%9A-sfyc23-blue.svg)](https://weibo.com/sfyc23)
+[![Weibo](https://img.shields.io/badge/Weibo-sfyc23-blue.svg)](https://weibo.com/sfyc23)
 [![API](https://img.shields.io/badge/API-%2B21-green.svg)](https://android-arsenal.com/api?level=21)
 [![](https://jitpack.io/v/sfyc23/CountTimeProgressView.svg)](https://jitpack.io/#sfyc23/CountTimeProgressView)
 [![License](https://img.shields.io/badge/License-Apache%202.0-red.svg)]()
 # CountTimeProgressView
 
 **CountTimeProgressView** - An Android library that provides a count time circular progress view effect.
 
-[中文版][1]
+[Chinese][1]
 
 ## Sample
-![页面动图][2]
+![Demo animation][2]
 
 
 ## Usage

app/build.gradle

@@ -45,7 +45,7 @@ dependencies {
     implementation 'androidx.viewpager2:viewpager2:1.0.0'
     implementation 'androidx.fragment:fragment-ktx:1.6.2'
 
-    // RecyclerView（导航首页列表）
+    // RecyclerView for the main navigation list
     implementation 'androidx.recyclerview:recyclerview:1.3.2'
 
     // Jetpack Compose

app/src/main/AndroidManifest.xml

@@ -8,7 +8,7 @@
         android:supportsRtl="true"
         android:theme="@style/AppTheme">
 
-        <!-- 闪屏页（启动入口） -->
+        <!-- Splash entry point -->
         <activity
             android:name=".SplashActivity"
             android:exported="true"
@@ -19,25 +19,25 @@
             </intent-filter>
         </activity>
 
-        <!-- 导航首页 -->
+        <!-- Main navigation page -->
         <activity android:name=".MainActivity" />
 
-        <!-- 传统演示页（兼容旧版） -->
+        <!-- Classic compatibility demo -->
         <activity android:name=".SimpleActivity" />
 
-        <!-- 动画控制页 -->
+        <!-- Animation control page -->
         <activity android:name=".animation.AnimationControlActivity" />
 
-        <!-- 场景：广告跳过 -->
+        <!-- Ad skip scenario -->
         <activity android:name=".scene.adskip.AdSkipSceneActivity" />
 
-        <!-- 场景：验证码倒计时 -->
+        <!-- Verification code timer scenario -->
         <activity android:name=".scene.verifycode.VerifyCodeSceneActivity" />
 
-        <!-- 场景：进度恢复 -->
+        <!-- Progress restore scenario -->
         <activity android:name=".scene.resume.ResumeProgressSceneActivity" />
 
-        <!-- 场景：考试计时器 -->
+        <!-- Exam timer scenario -->
         <activity android:name=".scene.exam.ExamTimerSceneActivity" />
 
     </application>

app/src/main/java/com/sfyc/simple/MainActivity.kt

@@ -6,6 +6,7 @@ import android.view.LayoutInflater
 import android.view.View
 import android.view.ViewGroup
 import android.widget.TextView
+import androidx.annotation.StringRes
 import androidx.appcompat.app.AppCompatActivity
 import androidx.recyclerview.widget.LinearLayoutManager
 import androidx.recyclerview.widget.RecyclerView
@@ -15,25 +16,21 @@ import com.sfyc.simple.scene.exam.ExamTimerSceneActivity
 import com.sfyc.simple.scene.resume.ResumeProgressSceneActivity
 import com.sfyc.simple.scene.verifycode.VerifyCodeSceneActivity
 
-/**
- * 导航首页。
- *
- * 以 Material Design 3 卡片列表展示所有演示页面入口，
- * 点击后跳转到对应的功能演示或真实场景页面。
- */
 class MainActivity : AppCompatActivity() {
 
-    /** 演示项数据类：标题 + 副标题 + 目标 Activity */
-    data class DemoItem(val title: String, val subtitle: String, val activityClass: Class<*>)
+    data class DemoItem(
+        @StringRes val titleResId: Int,
+        @StringRes val subtitleResId: Int,
+        val activityClass: Class<*>
+    )
 
-    /** 导航列表数据源 */
     private val items = listOf(
-        DemoItem("动画控制", "开始 / 暂停 / 恢复 / 重置 / 实时状态", AnimationControlActivity::class.java),
-        DemoItem("场景：广告跳过", "真实闪屏广告跳过场景", AdSkipSceneActivity::class.java),
-        DemoItem("场景：验证码倒计时", "发送验证码后的倒计时按钮", VerifyCodeSceneActivity::class.java),
-        DemoItem("场景：进度恢复", "从服务器剩余时间恢复 / 屏幕旋转恢复", ResumeProgressSceneActivity::class.java),
-        DemoItem("场景：考试计时器", "长时间倒计时 + 警告 + 暂停恢复", ExamTimerSceneActivity::class.java),
-        DemoItem("传统演示页", "原始参数面板（兼容旧版）", SimpleActivity::class.java),
+        DemoItem(R.string.nav_animation, R.string.nav_animation_desc, AnimationControlActivity::class.java),
+        DemoItem(R.string.nav_ad_skip, R.string.nav_ad_skip_desc, AdSkipSceneActivity::class.java),
+        DemoItem(R.string.nav_verify_code, R.string.nav_verify_code_desc, VerifyCodeSceneActivity::class.java),
+        DemoItem(R.string.nav_resume, R.string.nav_resume_desc, ResumeProgressSceneActivity::class.java),
+        DemoItem(R.string.nav_exam, R.string.nav_exam_desc, ExamTimerSceneActivity::class.java),
+        DemoItem(R.string.nav_legacy, R.string.nav_legacy_desc, SimpleActivity::class.java),
     )
 
     override fun onCreate(savedInstanceState: Bundle?) {
@@ -47,9 +44,6 @@ class MainActivity : AppCompatActivity() {
         }
     }
 
-    /**
-     * 导航列表适配器，每个 item 显示卡片标题和描述。
-     */
     class DemoAdapter(
         private val items: List<DemoItem>,
         private val onClick: (DemoItem) -> Unit
@@ -68,8 +62,8 @@ class MainActivity : AppCompatActivity() {
 
         override fun onBindViewHolder(holder: VH, position: Int) {
             val item = items[position]
-            holder.tvTitle.text = item.title
-            holder.tvSubtitle.text = item.subtitle
+            holder.tvTitle.setText(item.titleResId)
+            holder.tvSubtitle.setText(item.subtitleResId)
             holder.itemView.setOnClickListener { onClick(item) }
         }