# 目录
-   [简介](#简介)
-   [文件位置](#文件位置)
-   [语言文件格式](#语言文件格式)
-   [使用例](#使用例)
-   [排版规范](#排版规范)
    -   [空格](#空格)
        - [中英文之间需要增加空格](#中英文之间需要增加空格)
        - [中文与数字之间需要增加空格](#中文与数字之间需要增加空格)
        - [数字与单位之间不加空格](#数字与单位之间不加空格)
        - [全角标点与其他字符之间不加空格](#全角标点与其他字符之间不加空格)
        - [变量与中文之间需要增加空格](#变量与中文之间需要增加空格)
    -   [标点符号](#标点符号)
        -   [不要重复使用标点符号](#不要重复使用标点符号)
        -   [简体中文不要使用直角引号](#简体中文不要使用直角引号)
        -   [英文不要使用弯引号](#英文不要使用弯引号)
        -   [英文省略号使用三个点](#英文省略号使用三个点)
    -   [全角和半角](#全角和半角)
        -   [使用全角中文标点](#使用全角中文标点)
        -   [数字和英文使用半角字符](#数字和英文使用半角字符)
        -   [完整的英文成句内容中使用半角标点](#完整的英文成句内容中使用半角标点)
    -   [名词](#名词)
        -   [专有名词使用正确的大小写](#专有名词使用正确的大小写)
        -   [不要使用非正式的缩写](#不要使用非正式的缩写)
        -   [不同地区的中文使用对应的地区词](#不同地区的中文使用对应的地区词)
-   [报告问题](#报告问题)

# 简介
本规范文件旨在确保项目中的多语言文本一致性和格式规范。请遵循以下内容以保持代码库中的多语言资源的统一性。

# 文件位置
请将语言文件放置在 `/locales` 目录中，并以语言代码命名为 JSON 文件。

根路径下的目录用于放置全局字符串，模块下的目录用于放置对应专用的模块字符串。

原则上，模块字符串和对应模块须对应，若模块之间存在关联则可以例外，否则请考虑转为全局字符串。

# 语言文件格式
请确保键名与字符串一一对应，不得嵌套。

**全局字符串的命名方式**：`字符串类别.用途`

**模块字符串的命名方式**：`模块名称.字符串类别.(命令名称.)用途`

使用 `${变量名}` 可表示变量，变量名须使用英文，不建议使用 Python 语句，禁止使用空格和特殊符号，如需分隔则请使用下划线代替。

# 使用例
在模块帮助中调用多语言字符串的示例：
```python3
from core.component import module

test = module('test', desc='{test.help.desc}')

@test.command('say <word> {{test.help.say}}')
...
```
在代码中调用多语言字符串的示例：
```python3
from core.builtins import Bot

async def test(msg: Bot.MessageSession):
...
    await msg.send_message(msg.locale.t("test.message.say.prompt"))
# 没有变量时可直接输出
    await msg.send_message(msg.locale.t("test.message.say.reply", sender=msg.target.sender_id))
# 若存在变量，则须将变量赋值后输出
# 如此处在字符串内的变量为 ${sender}，并被赋值为 Bot.MessageSession.target.sender_id
```

# 排版规范
> 本文部分参照[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)，内容可能有出入。

太长不看：半角符号和全角符号（标点除外）之间用空格隔开，正确使用对应语言的标点符号
和用词习惯。

## 空格
### 中英文之间需要增加空格
正确：
> 在 IBM 的研究中，他们利用 AI 技术开发了一种先进的语音识别系统。

错误：
> 在IBM的研究中，他们利用AI技术开发了一种先进的语音识别系统。

例外：专有名词、商品名等词语，按照约定俗成的格式书写。

### 中文与数字之间需要增加空格
正确：
  > 今年的全球汽车销售量达到了 8000 万辆。

错误：
  > 今年的全球汽车销售量达到了8000万辆。

### 数字与单位之间不加空格
正确：
> 我家的光纤入户宽带有 10Gbps，SSD 一共有 10TB。

> 这个城市每年平均降雨量为 1200mm。
>
> 角度为 90° 的角，就是直角。

错误：
>我家的光纤入户宽带有 10 Gbps，SSD 一共有 20 TB。

> 这个城市每年平均降雨量为 1200 mm。
>
> 角度为 90 ° 的角，就是直角。

### 全角标点与其他字符之间不加空格
正确：
> 刚刚买了一部 iPhone，好开心！

错误：
> 刚刚买了一部 iPhone ，好开心！

### 变量与中文之间需要增加空格
变量的输入一般为英文或数字，故变量与中文之间须加入空格。

正确：
> 你扔了一块石头，漂了 ${count} 下。

错误：
> 你扔了一块石头，漂了${count}下。

例外：如果变量的输入确保为中文，则可以不加空格。

## 标点符号
### 不要重复使用标点符号
虽然重复使用标点符号在规范中是被允许的行为，但是请不要这样做。

正确：
> 德国队竟然战胜了巴西队！

错误：
> 德国队竟然战胜了巴西队！！！

### 简体中文不要使用直角引号
直角引号并不符合简体中文使用者的使用习惯。

正确：
> “老师，‘有条不紊’的‘紊’是什么意思？”

错误：
> 「老师，『有条不紊』的『紊』是什么意思？」

### 英文不要使用弯引号
中文弯引号和英文弯引号属于同一个字符，如果使用弯引号反而会造成阅读问题。请使用直引号 `"`。

正确：
> "Success is not final, failure is not fatal: It is the courage to continue that counts."

错误：
> “Success is not final, failure is not fatal: It is the courage to continue that counts.”

### 英文省略号使用三个点
原因同上。请使用三个点 `...`。

正确：
> In the serene moonlit night, whispers of ancient tales lingered, echoing through the stillness of time...

错误：
> In the serene moonlit night, whispers of ancient tales lingered, echoing through the stillness of time…

## 全角和半角
### 使用全角中文标点
正确：
> 嗨！你知道嘛？今天前台的小妹跟我说“喵”了哎！

错误：
> 嗨! 你知道嘛? 今天前台的小妹跟我说 "喵" 了哎!
>
> 嗨!你知道嘛?今天前台的小妹跟我说"喵"了哎!

### 数字和英文使用半角字符
正确：
> 这件蛋糕只卖 200 元。

错误：
> 这件蛋糕只卖 ２００ 元。

### 完整的英文成句内容中使用半角标点
正确：
> 乔布斯那句话是怎么说的？“Stay hungry, stay foolish.”

错误：
> 乔布斯那句话是怎么说的？“Stay hungry，stay foolish。”

## 名词
### 专有名词使用正确的大小写
正确：
> 使用 GitHub 登录

错误：
> 使用 Github 登录
> 
> 使用 gitHub 登录
> 
> 使用 github 登录
> 
> 使用 GITHUB 登录

### 不要使用非正式的缩写
正确：
> 我们需要一位熟悉 JavaScript、HTML5，至少理解一种框架（如 Backbone.js、AngularJS、React 等）的前端开发者。

错误：
> 我们需要一位熟悉 Js、h5，至少理解一种框架（如 backbone、angular、RJS 等）的 FED。


### 不同地区的中文使用对应的地区词
不要在繁体中文中使用“视频”等错误的地区词，这不是玩笑。

正确：
> 輸入影片編號取得對應資訊。

错误：
> 輸入視頻編號獲得相應信息。

例外：专有名词、商品名等词语，按照约定俗成的格式书写。

# 报告问题
与简体中文相关的问题可直接使用 [Issue](https://github.com/Teahouse-Studios/akari-bot/issues/new) 报告。

简体中文以外的所有语言由机器人 @Hldbot 维护，相关问题请移步 [Crowdin](https://crowdin.com/project/akari-bot) 报告。