Merge pull request #77 from lobehub/contributing

chore: 添加 wiki sync workflow 和 贡献文档

.github/workflows/wiki-sync.yml

@@ -0,0 +1,19 @@
+name: Wiki Sync
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'contributing/**'
+    branches:
+      - main
+
+jobs:
+  update-wiki:
+    runs-on: ubuntu-latest
+    name: Wiki sync
+    steps:
+      - uses: OrlovM/Wiki-Action@v1
+        with:
+          path: 'contributing'
+          token: ${{ secrets.GH_TOKEN }}

contributing/Internationalization/Add-New-Locale.md

@@ -0,0 +1,62 @@
+# New Locale Guide
+
+LobeVidol uses [lobe-i18n](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n) as the i18n solution, which allows for quick addition of new language support in the application.
+
+## TOC
+
+- [Adding New Language Support](#adding-new-language-support)
+  - [Step 1: Update the Internationalization Configuration File](#step-1-update-the-internationalization-configuration-file)
+  - [Step 2: Automatically Translate Language Files](#step-2-automatically-translate-language-files)
+  - [Step 3: Submit and Review Your Changes](#step-3-submit-and-review-your-changes)
+  - [Additional Information](#additional-information)
+
+## Adding New Language Support
+
+To add new language internationalization support in (for example, adding Vietnamese `vi-VN`), please follow the steps below:
+
+### Step 1: Update the Internationalization Configuration File
+
+1. Open the `.i18nrc.js` file. You can find this file in the project's root directory.
+2. Add the new language code to the configuration file. For example, to add Vietnamese, you need to add `'vi-VN'` to the configuration file.
+
+```js
+module.exports = {
+  // ... Other configurations
+
+  outputLocales: [
+    'zh-TW',
+    'en-US',
+    'ru-RU',
+    'ja-JP',
+    // ...Other languages
+
+    'vi-VN', // Add 'vi-VN' to the array
+  ],
+};
+```
+
+### Step 2: Automatically Translate Language Files
+
+uses the `lobe-i18n` tool to automatically translate language files, so manual updating of i18n files is not required.
+
+Run the following command to automatically translate and generate the Vietnamese language files:
+
+```bash
+npm run i18n
+```
+
+This will utilize the `lobe-i18n` tool to process the language files.
+
+### Step 3: Submit and Review Your Changes
+
+Once you have completed the above steps, you need to submit your changes and create a Pull Request.
+
+Ensure that you follow 's contribution guidelines and provide a necessary description to explain your changes. For example, refer to a similar previous Pull Request [#759](https://github.com/lobehub/lobe-chat/pull/759).
+
+### Additional Information
+
+- After submitting your Pull Request, please patiently wait for the project maintainers to review it.
+- If you encounter any `issues`, you can reach out to the community for assistance.
+- For more accurate results, ensure that your Pull Request is based on the latest main branch and stays in sync with the main branch.
+
+By following the above steps, you can successfully add new language support to and ensure that the application provides a localized experience for more users.

contributing/Internationalization/Add-New-Locale.zh-CN.md

@@ -0,0 +1,62 @@
+# 新语种添加指南
+
+使用 [lobe-i18n](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n) 作为 i18n 解决方案，可以在应用中快速添加新的语言支持。
+
+## TOC
+
+- [添加新的语言支持](#添加新的语言支持)
+  - [步骤 1: 更新国际化配置文件](#步骤-1-更新国际化配置文件)
+  - [步骤 2: 自动翻译语言文件](#步骤-2-自动翻译语言文件)
+  - [步骤 3: 提交和审查你的更改](#步骤-3-提交和审查你的更改)
+  - [附加信息](#附加信息)
+
+## 添加新的语言支持
+
+为了在 中添加新的语言国际化支持，（例如添加越南语 `vi-VN`)，请按照以下步骤操作：
+
+### 步骤 1: 更新国际化配置文件
+
+1. 打开 `.i18nrc.js` 文件。你可以在项目的根目录中找到此文件。
+2. 将新的语言代码添加到配置文件中。例如，为了添加越南语，你需要在配置文件中添加 `'vi-VN'`。
+
+```js
+module.exports = {
+  // ... 其他配置
+
+  outputLocales: [
+    'zh-TW',
+    'en-US',
+    'ru-RU',
+    'ja-JP',
+    // ...其他语言
+
+    'vi-VN', // 在数组中添加 'vi-VN'
+  ],
+};
+```
+
+### 步骤 2: 自动翻译语言文件
+
+使用 `lobe-i18n` 工具来自动翻译语言文件，因此不需要手动更新 i18n 文件。
+
+运行以下命令来自动翻译并生成越南语的语言文件：
+
+```bash
+npm run i18n
+```
+
+这将会利用 `lobe-i18n` 工具来处理语言文件。
+
+### 步骤 3: 提交和审查你的更改
+
+一旦你完成了上述步骤，你需要提交你的更改并创建一个 Pull Request。
+
+请确保你遵循了 的贡献指南，并提供必要的描述来说明你的更改。例如，参考之前的类似 Pull Request [#759](https://github.com/lobehub/lobe-chat/pull/759)。
+
+### 附加信息
+
+- 提交你的 Pull Request 后，请耐心等待项目维护人员的审查。
+- 如果遇到任何问题，可以联系 社区寻求帮助。
+- 为了更精确的结果，确保你的 Pull Request 是基于最新的主分支，并且与主分支保持同步。
+
+通过遵循上述步骤，你可以成功为 添加新的语言支持，并且确保应用能够为更多用户提供本地化的体验。

contributing/Internationalization/Internationalization-Implementation.md

@@ -0,0 +1,125 @@
+# Internationalization Implementation Guide
+
+Welcome to the Internationalization Implementation Guide. This document will guide you through understanding the internationalization mechanism of , including file structure and how to add new languages. uses `i18next` and `lobe-i18n` as the internationalization solution, aiming to provide users with seamless multilingual support.
+
+## TOC
+
+- [Internationalization Overview](#internationalization-overview)
+- [File Structure](#file-structure)
+- [Core Implementation Logic](#core-implementation-logic)
+- [Adding Support for New Languages](#adding-support-for-new-languages)
+- [Resources and Further Reading](#resources-and-further-reading)
+
+## Internationalization Overview
+
+Internationalization (i18n for short) is the process of enabling an application to adapt to different languages and regions. In , we support multiple languages and achieve dynamic language switching and content localization through the `i18next` library. Our goal is to provide a localized experience for global users.
+
+## File Structure
+
+In the project, internationalization-related files are organized as follows:
+
+- `src/locales/default`: Contains translation files for the default development language (Chinese), which we use as Chinese.
+- `locales`: Contains folders for all supported languages, with each language folder containing the respective translation files generated by lobe-i18n.
+
+In the directory structure of `src/locales`, the `default` folder contains the original translation files (Chinese), while each other language folder contains JSON translation files for the respective language. The files in each language folder correspond to the TypeScript files in the `default` folder, ensuring consistency in the structure of translation files across languages.
+
+```
+src/locales
+├── create.ts
+├── default
+│   ├── chat.ts
+│   ├── common.ts
+│   ├── error.ts
+│   ├── index.ts
+│   ├── market.ts
+│   ├── migration.ts
+│   ├── plugin.ts
+│   ├── setting.ts
+│   ├── tool.ts
+│   └── welcome.ts
+└── resources.ts
+```
+
+The file structure generated by lobe-i18n is as follows:
+
+```
+locales
+├── ar
+│   ├── chat.json
+│   ├── common.json
+│   ├── error.json
+│   └── ... (other translation files)
+├── de-DE
+│   ├── chat.json
+│   ├── common.json
+│   ├── error.json
+│   └── ... (other translation files)
+├── en-US
+├── ... (other language directories)
+├── zh-CN
+└── zh-TW
+```
+
+## Core Implementation Logic
+
+The internationalization core implementation logic of is as follows:
+
+- Initialize and configure using the `i18next` library.
+- Automatically detect the user's language preference using `i18next-browser-languagedetector`.
+- Dynamically load translation resources using `i18next-resources-to-backend`.
+- Set the direction of the HTML document (LTR or RTL) based on the user's language preference.
+
+Here is a simplified pseudo code example to illustrate the core implementation logic of internationalization in :
+
+```ts
+import i18n from 'i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import resourcesToBackend from 'i18next-resources-to-backend';
+import { isRtlLang } from 'rtl-detect';
+
+// Create i18n instance and configure
+const createI18nInstance = (lang) => {
+  const i18nInstance = i18n
+    .use(LanguageDetector) // Use language detection
+    .use(
+      resourcesToBackend((language, namespace) => {
+        // Dynamically load translation resources for the corresponding language
+        return import(`path/to/locales/${language}/${namespace}.json`);
+      }),
+    );
+
+  // Listen for language change events and dynamically set document direction
+  i18nInstance.on('languageChanged', (language) => {
+    const direction = isRtlLang(language) ? 'rtl' : 'ltr';
+    document.documentElement.dir = direction; // Set HTML document direction
+  });
+
+  // Initialize i18n instance
+  i18nInstance.init({
+    // Relevant configurations
+  });
+
+  return i18nInstance;
+};
+```
+
+In this example, we demonstrate how to use `i18next` and related plugins to initialize internationalization settings. We dynamically import translation resources and respond to language change events to adjust the text direction of the page. This process provides with flexible multilingual support capabilities.
+
+## Adding Support for New Languages
+
+We have already supported a variety of languages globally through the following efforts:
+
+- [✨ feat: adding Arabic Language Support #1049](https://github.com/lobehub/lobe-chat/pull/1049)
+- [🌐 style: Add Vietnamese files and add the vi-VN option in the General Settings #860](https://github.com/lobehub/lobe-chat/pull/860)
+- [🌐 style: support it-IT nl-NL and pl-PL locales #759](https://github.com/lobehub/lobe-chat/pull/759)
+- [🌐 feat(locale): Add fr-FR (#637) #645](https://github.com/lobehub/lobe-chat/pull/645)
+- [🌐 Add russian localy #137](https://github.com/lobehub/lobe-chat/pull/137)
+
+To add support for new languages, please refer to the detailed steps in the [New Locale Addition Guide](Add-New-Locale.en-US).
+
+## Resources and Further Reading
+
+- [i18next Official Documentation](https://www.i18next.com/)
+- [lobe-i18n Tool Description](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n)
+
+By following this guide, you can better understand and participate in the internationalization work of , providing a seamless multilingual experience for global users.

contributing/Internationalization/Internationalization-Implementation.zh-CN.md

@@ -0,0 +1,125 @@
+# 国际化实现指南
+
+欢迎阅读 国际化实现指南。本文档将指导你了解 的国际化机制，包括文件结构、如何添加新语种。 采用 `i18next` 和 `lobe-i18n` 作为国际化解决方案，旨在为用户提供流畅的多语言支持。
+
+## TOC
+
+- [国际化概述](#国际化概述)
+- [文件结构](#文件结构)
+- [核心实现逻辑](#核心实现逻辑)
+- [添加新的语言支持](#添加新的语言支持)
+- [资源和进一步阅读](#资源和进一步阅读)
+
+## 国际化概述
+
+国际化（Internationalization，简称为 i18n）是一个让应用能够适应不同语言和地区的过程。在 中，我们支持多种语言，并通过 `i18next` 库来实现语言的动态切换和内容的本地化。我们的目标是让 能够为全球用户提供本地化的体验。
+
+## 文件结构
+
+在 的项目中，国际化相关的文件被组织如下：
+
+- `src/locales/default`: 包含默认开发语言（中文）的翻译文件，我们作为中文。
+- `locales`: 包含所有支持的语言文件夹，每个语言文件夹中包含相应语言的翻译文件，这些翻译文件通过 lobe-i18n 自动生成。
+
+在 `src/locales` 这个目录结构中，`default` 文件夹包含了原始的翻译文件（中文），其他每个语言文件夹则包含了相应语言的 JSON 翻译文件。每个语言文件夹中的文件对应 `default` 文件夹中的 TypeScript 文件，确保了各语种之间的翻译文件结构一致性。
+
+```
+src/locales
+├── create.ts
+├── default
+│   ├── chat.ts
+│   ├── common.ts
+│   ├── error.ts
+│   ├── index.ts
+│   ├── market.ts
+│   ├── migration.ts
+│   ├── plugin.ts
+│   ├── setting.ts
+│   ├── tool.ts
+│   └── welcome.ts
+└── resources.ts
+```
+
+通过 lobe-i18n 自动生成的文件结构如下：
+
+```
+locales
+├── ar
+│   ├── chat.json
+│   ├── common.json
+│   ├── error.json
+│   └── ... (其他翻译文件)
+├── de-DE
+│   ├── chat.json
+│   ├── common.json
+│   ├── error.json
+│   └── ... (其他翻译文件)
+├── en-US
+├── ... (其他语种目录）
+├── zh-CN
+└── zh-TW
+```
+
+## 核心实现逻辑
+
+的国际化核心实现逻辑如下：
+
+- 使用 `i18next` 库进行初始化和配置。
+- 使用 `i18next-browser-languagedetector` 自动检测用户的语言偏好。
+- 使用 `i18next-resources-to-backend` 动态加载翻译资源。
+- 根据用户的语言偏好，设置 HTML 文档的方向（LTR 或 RTL）。
+
+以下是一个简化的伪代码示例，用以说明 国际化的核心实现逻辑：
+
+```ts
+import i18n from 'i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import resourcesToBackend from 'i18next-resources-to-backend';
+import { isRtlLang } from 'rtl-detect';
+
+// 创建 i18n 实例并配置
+const createI18nInstance = (lang) => {
+  const i18nInstance = i18n
+    .use(LanguageDetector) // 使用语言检测
+    .use(
+      resourcesToBackend((language, namespace) => {
+        // 动态加载对应语言的翻译资源
+        return import(`path/to/locales/${language}/${namespace}.json`);
+      }),
+    );
+
+  // 监听语言变化事件，动态设置文档方向
+  i18nInstance.on('languageChanged', (language) => {
+    const direction = isRtlLang(language) ? 'rtl' : 'ltr';
+    document.documentElement.dir = direction; // 设置 HTML 文档方向
+  });
+
+  // 初始化 i18n 实例
+  i18nInstance.init({
+    // 相关配置
+  });
+
+  return i18nInstance;
+};
+```
+
+在这个示例中，我们展示了如何使用 `i18next` 和相关插件来初始化国际化设置。我们动态导入了翻译资源，并响应语言变化事件来调整页面的文本方向。这个过程为 提供了灵活的多语言支持能力。
+
+## 添加新的语言支持
+
+我们通过以下工作，已经支持了全球多种语言：
+
+- [✨ feat: adding Arabic Language Support #1049](https://github.com/lobehub/lobe-chat/pull/1049)
+- [🌐 style: Add Vietnamese files and add the vi-VN option in the General Settings #860](https://github.com/lobehub/lobe-chat/pull/860)
+- [🌐 style: support it-IT nl-NL and pl-PL locales #759](https://github.com/lobehub/lobe-chat/pull/759)
+- [🌐 feat(locale): Add fr-FR (#637) #645](https://github.com/lobehub/lobe-chat/pull/645)
+- [🌐 Add russian localy #137](https://github.com/lobehub/lobe-chat/pull/137)
+
+要添加新的语种支持， 详细步骤请参考：[新语种添加指南](Add-New-Locale.zh-CN.md)。
+
+## 资源和进一步阅读
+
+- [i18next 官方文档](https://www.i18next.com/)
+- [lobe-i18n 工具说明](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n)
+
+通过遵循本指南，你可以更好地理解和参与到 的国际化工作中，为全球用户提供无缝的多语言体验。

contributing/_Footer.md

@@ -0,0 +1 @@
+This is the **🤗 / 🤖 Lobe Vidol** wiki. [Wiki Home](https://github.com/lobehub/lobe-vidol/wiki)