# generaltranslation: General Translation Core SDK: 概述
URL: https://generaltranslation.com/zh/docs/core.mdx
---
title: 概述
description: generaltranslation 库概述
---

## 简介

`generaltranslation` 库是 GT 的核心 i18n 库，提供用于翻译和格式化的实用函数与类。
它通常与 `gt-next`、`gt-react` 等框架包配合使用，但也可以作为独立库单独使用。

import Video from '@/components/Video';

<Video src="https://assets.gtx.dev/core-demo.mp4" />

```typescript title="index.ts"
import { GT } from 'generaltranslation';

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  sourceLocale: 'en',
  targetLocale: 'es',
});

// 翻译内容
const result = await gt.translate('Hello, world!', 'es');
// "¡Hola, mundo!"

// 格式化数字、日期、货币
const formattedPrice = gt.formatNum(29.99, { style: 'currency', currency: 'USD' });
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "9/25/2025"

// 处理区域设置
const localeProps = gt.getLocaleProperties('fr-CA');
const isValid = gt.isValidLocale('de');
// { language: "fr", region: "CA", ... }
// true
```

***


## 安装

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install generaltranslation
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add generaltranslation
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add generaltranslation
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add generaltranslation
    ```
  </Tab>
</Tabs>

***

## 示例

翻译主要分为两类：字符串翻译和文件翻译。

### 设置

要启用翻译，您需要提供项目 ID 和 API 密钥。
有关更多信息，请参阅 [`constructor`](/docs/core/class/constructor) 方法。

```typescript
const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  targetLocale: 'es',
});
```


### 字符串翻译

更多信息请参阅 [`translate`](/docs/core/class/methods/translation/translate) 方法。

```typescript
try {
  const result = await gt.translate('Hello, world!');
  console.log(result); // "¡Hola, mundo!"
} catch (error) {
  console.error('翻译失败:', error.message);
}
```


### 文件翻译

文件会以任务的形式进行翻译。
你可以通过上传文件来发起任务。
上传多个文件会发起多个任务。

更多信息请参阅 [`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files)
和 [`queryFileData`](/docs/core/class/methods/translation/query-file-data) 方法。

```typescript
// 要上传的文件
const files = [
  {
    source: {
      fileName: 'src/components/Button.tsx',
      fileFormat: 'TSX',
      locale: 'en',
      content: '...',
    },
  },
];

// 上传源文件
await gt.uploadSourceFiles(files);
```

***


## 目录

### GT 类

负责翻译和区域设置功能的主要类：

* **[Constructor](/docs/core/class/constructor)** - 使用配置初始化 GT 实例
* **[setConfig](/docs/core/class/set-config)** - 更新 GT 实例的配置

#### 翻译方法

* **[translate](/docs/core/class/methods/translation/translate)** - 核心翻译功能
* **[translateMany](/docs/core/class/methods/translation/translate-many)** - 批量翻译
* **[setupProject](/docs/core/class/methods/translation/setup-project)** - 项目初始化
* **[checkJobStatus](/docs/core/class/methods/translation/check-job-status)** - 检查任务进度
* **[getProjectData](/docs/core/class/methods/translation/get-project-data)** - 获取项目信息
* **[uploadSourceFiles](/docs/core/class/methods/translation/upload-source-files)** - 上传待翻译文件
* **[uploadTranslations](/docs/core/class/methods/translation/upload-translations)** - 上传现有译文
* **[enqueueFiles](/docs/core/class/methods/translation/enqueue-files)** - 将文件加入处理队列
* **[queryFileData](/docs/core/class/methods/translation/query-file-data)** - 查询翻译状态
* **[downloadFile](/docs/core/class/methods/translation/download-file)** - 下载单个文件
* **[downloadFileBatch](/docs/core/class/methods/translation/download-file-batch)** - 下载多个文件
* **[querySourceFile](/docs/core/class/methods/translation/query-source-file)** - 查询源文件信息

#### 格式化方法

* **[formatMessage](/docs/core/class/methods/formatting/format-message)** - 国际化文本格式化
* **[formatNum](/docs/core/class/methods/formatting/format-num)** - 数字格式化
* **[formatDateTime](/docs/core/class/methods/formatting/format-date-time)** - 日期和时间格式化
* **[formatRelativeTime](/docs/core/class/methods/formatting/format-relative-time)** - 使用显式时间单位的相对时间格式化
* **[formatRelativeTimeFromDate](/docs/core/class/methods/formatting/format-relative-time-from-date)** - 基于 Date 的相对时间格式化
* **[formatCutoff](/docs/core/class/methods/formatting/format-cutoff)** - 文本截断格式化
* **[formatListToParts](/docs/core/class/methods/formatting/format-list-to-parts)** - 列表分段格式化

#### 区域设置方法

* **[getLocaleName](/docs/core/class/methods/locales/get-locale-name)** - 获取区域设置显示名称
* **[getLocaleProperties](/docs/core/class/methods/locales/get-locale-properties)** - 获取完整的区域设置信息
* **[getLocaleDirection](/docs/core/class/methods/locales/get-locale-direction)** - 获取区域设置的文本方向
* **[getLocaleEmoji](/docs/core/class/methods/locales/get-locale-emoji)** - 获取区域设置的旗帜表情
* **[getRegionProperties](/docs/core/class/methods/locales/get-region-properties)** - 获取地区信息及属性
* **[isValidLocale](/docs/core/class/methods/locales/is-valid-locale)** - 验证区域设置代码
* **[resolveAliasLocale](/docs/core/class/methods/locales/resolve-alias-locale)** - 将标准区域设置转换为别名区域设置
* **[resolveCanonicalLocale](/docs/core/class/methods/locales/resolve-canonical-locale)** - 将别名区域设置转换为标准区域设置
* **[standardizeLocale](/docs/core/class/methods/locales/standardize-locale)** - 标准化区域设置代码格式
* **[isSameDialect](/docs/core/class/methods/locales/is-same-dialect)** - 检查区域设置是否表示相同方言
* **[isSameLanguage](/docs/core/class/methods/locales/is-same-language)** - 检查区域设置是否表示相同语言
* **[isSupersetLocale](/docs/core/class/methods/locales/is-superset-locale)** - 检查区域设置的层级关系
* **[determineLocale](/docs/core/class/methods/locales/determine-locale)** - 根据偏好查找最佳匹配的区域设置
* **[requiresTranslation](/docs/core/class/methods/locales/requires-translation)** - 判断是否需要翻译

### 工具函数

#### 格式化函数

* **[formatMessage](/docs/core/functions/formatting/format-message)** - 独立文本格式化
* **[formatNum](/docs/core/functions/formatting/format-num)** - 独立数字格式化
* **[formatDateTime](/docs/core/functions/formatting/format-date-time)** - 独立日期/时间格式化
* **[formatRelativeTime](/docs/core/functions/formatting/format-relative-time)** - 独立相对时间格式化
* **[formatRelativeTimeFromDate](/docs/core/functions/formatting/format-relative-time-from-date)** - 独立基于 Date 的相对时间格式化
* **[formatCutoff](/docs/core/functions/formatting/format-cutoff)** - 独立文本截断格式化
* **[formatListToParts](/docs/core/functions/formatting/format-list-to-parts)** - 独立列表分段格式化

#### 区域设置函数

* **[getLocaleName](/docs/core/functions/locales/get-locale-name)** - 独立的区域设置名称工具
* **[getLocaleProperties](/docs/core/functions/locales/get-locale-properties)** - 独立的区域设置属性
* **[getLocaleDirection](/docs/core/functions/locales/get-locale-direction)** - 独立的文本方向工具
* **[getLocaleEmoji](/docs/core/functions/locales/get-locale-emoji)** - 独立的表情符号工具
* **[getRegionProperties](/docs/core/functions/locales/get-region-properties)** - 独立的地区属性工具
* **[isValidLocale](/docs/core/functions/locales/is-valid-locale)** - 独立的区域设置验证
* **[resolveAliasLocale](/docs/core/functions/locales/resolve-alias-locale)** - 独立的别名区域设置解析
* **[standardizeLocale](/docs/core/functions/locales/standardize-locale)** - 独立的区域设置标准化
* **[isSameDialect](/docs/core/functions/locales/is-same-dialect)** - 独立的方言比较
* **[isSameLanguage](/docs/core/functions/locales/is-same-language)** - 独立的语言比较
* **[isSupersetLocale](/docs/core/functions/locales/is-superset-locale)** - 独立的区域设置超集关系检查
* **[determineLocale](/docs/core/functions/locales/determine-locale)** - 独立的区域设置协商
* **[requiresTranslation](/docs/core/functions/locales/requires-translation)** - 独立的翻译需求判定

### 类型和接口

TypeScript 定义：

* **[GTConstructorParams](/docs/core/types/gt-constructor-params)** - 配置选项
* **[LocaleProperties](/docs/core/types/locale-properties)** - 完整的区域设置信息
* **[TranslationResult](/docs/core/types/translation-result)** - 翻译结果类型
* **[TranslateManyResult](/docs/core/types/translate-many-result)** - 批量翻译响应类型
* **[FileToTranslate](/docs/core/types/file-to-translate)** - 文件翻译配置
* **[EnqueueFilesOptions](/docs/core/types/enqueue-files-options)** - 文件入队选项
* **[Entry](/docs/core/types/Entry)** - 翻译条目结构
* **[EntryMetadata](/docs/core/types/entry-metadata)** - 条目元数据信息
* **[Content](/docs/core/types/Content)** - 内容类型定义
* **[Variable](/docs/core/types/Variable)** - 变量结构
* **[VariableType](/docs/core/types/variable-type)** - 变量类型定义
* **[JsxElement](/docs/core/types/jsx-element)** - JSX 元素类型
* **[JsxChild](/docs/core/types/jsx-child)** - JSX 子节点类型
* **[JsxChildren](/docs/core/types/jsx-children)** - JSX 子节点集合类型
* **[DataFormat](/docs/core/types/data-format)** - 数据格式规范
* **[CustomMapping](/docs/core/types/custom-mapping)** - 自定义映射配置

***

## 后续步骤

* **[开始使用 GT 类](/docs/core/class/constructor)**
* **[了解翻译方法](/docs/core/class/methods/translation/translate)**
* **[了解区域设置实用工具](/docs/core/class/methods/locales/get-locale-name)**
* **[查看格式化选项](/docs/core/class/methods/formatting/format-message)**
* **[浏览独立函数](/docs/core/functions/formatting/format-message)**

如需了解特定框架的用法，请参阅 [Next.js](/docs/next) 或 [React](/docs/react) 文档。