timi/timi-lang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

add comprehensive javadoc comments for all classes

Browse Source 
- Add class-level documentation for all mapper and multilingual classes
- Add complete javadoc for all public methods with @param and @return tags
- Add field-level comments for better code readability
- Improve documentation for initialization blocks and constructors

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Timi
2026-01-13 15:33:25 +08:00
parent 42dd04c2a5
commit 20bef9263b
9 changed files with 165 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -1,3 +1,7 @@
/.claude
/CLAUDE.md
/AGENTS.md
target/
!.mvn/wrapper/maven-wrapper.jar
!**/src/main/**/target/

34
src/main/java/com/imyeyu/lang/mapper/AbstractLanguageMapper.java
View File

@ -7,35 +7,69 @@ import com.imyeyu.utils.StringInterpolator;
import java.util.Map;
/**
* 抽象语言映射器，提供语言映射的基础实现，提供字符串插值、调试模式等基础功能
*
* @author 夜雨
* @version 2024-04-01 16:25
*/
public abstract class AbstractLanguageMapper implements LanguageMapping {
/** 字符串插值器，用于处理占位符替换 */
protected final StringInterpolator INTERPOLATOR = StringInterpolator.createDollarInterpolator();
/** 当前映射器所属语言 */
protected final Language.Enum language;
/** 是否启用调试模式，启用后将抛出异常而不是返回默认值 */
protected boolean isDebugging = false;
/**
* 构造语言映射器
*
* @param language 所属语言
*/
public AbstractLanguageMapper(Language.Enum language) {
this.language = language;
}
/**
* 获取当前映射器所属语言
*
* @return 语言枚举
*/
public Language.Enum getLanguage() {
return language;
}
/**
* 设置调试模式，调试模式下，找不到映射时将抛出异常而不是返回默认值
*
* @param debugging true 为启用调试模式
*/
public void setDebugging(boolean debugging) {
isDebugging = debugging;
}
/**
* 获取文本
*
* @param key 键
* @param def 默认值（没有找到映射值时）
* @return 获取结果
*/
@Override
public String text(String key, String def) {
String result = text(key);
return result.equals(key) ? def : result;
}
/**
* 插入参数获取文本，使用 ${key} 格式进行占位符替换
*
* @param key 键
* @param args 参数映射表
* @return 替换占位符后的文本
*/
@Override
public String textArgs(String key, Map<String, Object> args) {
return INTERPOLATOR.inject(text(key), args);

7
src/main/java/com/imyeyu/lang/mapper/FileLanguageMap.java
View File

@ -8,6 +8,8 @@ import java.io.InputStreamReader;
import java.util.Properties;
/**
* 文件语言映射
*
* @author 夜雨
* @version 2024-04-09 01:00
*/
@ -22,6 +24,11 @@ public class FileLanguageMap extends PropertiesLanguageMap {
super(language);
}
/**
* 加载资源文件，格式化 % 为 {@link Language.Enum#toString()}，示例：lang/app_%s.lang
*
* @param path 路径
*/
public void load(String path) {
try {
InputStream is = IO.getInputStream(path.formatted(language.toString()));

27
src/main/java/com/imyeyu/lang/mapper/LanguageMap.java
View File

@ -10,13 +10,20 @@ import java.util.LinkedHashMap;
import java.util.Map;
/**
* 基于内存的语言映射实现
* <p>
* 使用 HashMap 存储语言映射关系，支持二次映射、模糊匹配等功能
* </p>
*
* @author 夜雨
* @version 2024-04-03 10:11
*/
public class LanguageMap extends AbstractLanguageMapper {
/** 语言键值映射表 */
protected final Map<String, String> map;
// 初始化字符串插值器过滤器，支持 @key 格式的语言映射引用
{
INTERPOLATOR.putFilter("lang", value -> {
if (value.startsWith("@")) {
@ -36,15 +43,35 @@ public class LanguageMap extends AbstractLanguageMapper {
this.map = new HashMap<>();
}
/**
* 合并另一个语言映射表
* <p>
* 将另一个映射表的所有键值对合并到当前映射表中，如果存在相同键则覆盖
* </p>
*
* @param map 要合并的语言映射表
*/
public void union(LanguageMap map) {
this.map.putAll(map.map);
}
/**
* 添加语言映射
*
* @param key 键
* @param value 值
*/
@Override
public void add(String key, String value) {
map.put(key, value);
}
/**
* 检查是否存在指定键的映射
*
* @param key 键
* @return true 为存在
*/
@Override
public boolean has(String key) {
return map.containsKey(key);

7
src/main/java/com/imyeyu/lang/mapper/PropertiesLanguageMap.java
View File

@ -6,6 +6,8 @@ import java.util.HashMap;
import java.util.Properties;
/**
* 基于 Properties 的语言映射实现
*
* @author 夜雨
* @version 2024-04-09 00:50
*/
@ -20,6 +22,11 @@ public class PropertiesLanguageMap extends LanguageMap {
super(language);
}
/**
* 从 Properties 对象加载语言映射数据
*
* @param properties 属性对象
*/
@SuppressWarnings({"unchecked", "rawtypes"})
public void load(Properties properties) {
map.putAll(new HashMap(properties));

8
src/main/java/com/imyeyu/lang/mapper/ResourcesLanguageMap.java
View File

@ -9,10 +9,13 @@ import java.io.InputStreamReader;
import java.util.Properties;
/**
* 资源文件语言映射
*
* @author 夜雨
* @version 2024-04-09 00:55
*/
public class ResourcesLanguageMap extends PropertiesLanguageMap {
/**
* 默认构造
*
@ -22,6 +25,11 @@ public class ResourcesLanguageMap extends PropertiesLanguageMap {
super(language);
}
/**
* 加载资源文件，格式化 % 为 {@link Language.Enum#toString()}，示例：lang/app_%s.lang
*
* @param path 路径
*/
public void load(String path) {
try {
InputStream is = IO.resourceToInputStream(getClass(), path.formatted(language.toString()));

20
src/main/java/com/imyeyu/lang/multi/FileMultilingual.java
View File

@ -6,11 +6,31 @@ import com.imyeyu.lang.mapper.FileLanguageMap;
import com.imyeyu.lang.mapper.LanguageMap;
/**
* 文件多语言实例，从文件系统加载多语言配置文件
*
* @author 夜雨
* @version 2024-04-09 01:06
*/
public class FileMultilingual extends Multilingual {
/**
* 构造并批量加载所有支持的语言文件
*
* @param path 文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
*/
public FileMultilingual(String path) {
addAll(path);
}
/**
* 批量加载所有支持的语言文件
* <p>
* 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并加载文件。
* 如果已存在相同语言的映射器，则合并映射数据
* </p>
*
* @param path 文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
*/
public void addAll(String path) {
Language.Enum[] values = Language.Enum.values();
for (int i = 0; i < values.length; i++) {

35
src/main/java/com/imyeyu/lang/multi/Multilingual.java
View File

@ -42,14 +42,24 @@ import java.util.Objects;
*/
public class Multilingual implements LanguageMapping {
/** 多语言映射表，存储各语言对应的映射器 */
protected final Map<Language.Enum, AbstractLanguageMapper> multilingualMap;
/** 激活语言更新回调列表 */
protected final List<CallbackArg<Language.Enum>> updateActiveListeners;
/** 当前激活语言 */
protected Language.Enum activated;
/** 是否启用调试模式 */
protected boolean isDebugging = false;
/**
* 默认构造
* <p>
* 根据系统默认 Locale 初始化激活语言，如果无法识别则默认为中文
* </p>
*/
public Multilingual() {
multilingualMap = new HashMap<>();
updateActiveListeners = new ArrayList<>();
@ -61,6 +71,12 @@ public class Multilingual implements LanguageMapping {
}
}
/**
* 添加语言映射器
*
* @param language 语言
* @param mapper 语言映射器
*/
public void add(Language.Enum language, AbstractLanguageMapper mapper) {
mapper.setDebugging(isDebugging);
multilingualMap.put(language, mapper);
@ -110,10 +126,23 @@ public class Multilingual implements LanguageMapping {
}
}
/**
* 获取当前激活的语言
*
* @return 当前激活语言
*/
public Language.Enum getActivated() {
return activated;
}
/**
* 设置调试模式
* <p>
* 同时会将所有已加载的语言映射器设置为调试模式
* </p>
*
* @param debugging true 为启用调试模式
*/
public void setDebugging(boolean debugging) {
isDebugging = debugging;
for (Map.Entry<Language.Enum, AbstractLanguageMapper> item : multilingualMap.entrySet()) {
@ -145,6 +174,12 @@ public class Multilingual implements LanguageMapping {
return multilingualMap.get(lang);
}
/**
* 向当前激活语言的映射表添加键值对
*
* @param key 键
* @param value 值
*/
@Override
public void add(String key, String value) {
multilingualMap.get(getActivated()).add(key, value);

23
src/main/java/com/imyeyu/lang/multi/ResourcesMultilingual.java
View File

@ -6,11 +6,34 @@ import com.imyeyu.lang.mapper.LanguageMap;
import com.imyeyu.lang.mapper.ResourcesLanguageMap;
/**
* 资源文件多语言实例
* <p>
* 从 classpath 资源文件加载多语言配置
* </p>
*
* @author 夜雨
* @version 2024-04-09 01:03
*/
public class ResourcesMultilingual extends Multilingual {
/**
* 构造并批量加载所有支持的语言资源文件
*
* @param path 资源文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
*/
public ResourcesMultilingual(String path) {
addAll(path);
}
/**
* 批量加载所有支持的语言资源文件
* <p>
* 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并从 classpath 加载资源。
* 如果已存在相同语言的映射器，则合并映射数据
* </p>
*
* @param path 资源文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
*/
public void addAll(String path) {
Language.Enum[] values = Language.Enum.values();
for (int i = 0; i < values.length; i++) {