# 국제화

- Human documentation: [https://docs.univer.ai/ko-KR/guides/docs/getting-started/i18n](https://docs.univer.ai/ko-KR/guides/docs/getting-started/i18n)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/docs/getting-started/i18n.md](https://docs.univer.ai/ko-KR/guides/docs/getting-started/i18n.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [docs/getting-started/i18n.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/getting-started/i18n.ko-KR.mdx)

---

## 인터페이스 언어

`locale`은 메뉴, 도구 설명, 대화 상자 등 UI의 언어 팩을 선택합니다. `locales`는 언어 팩을 등록하며 언어를 선택하지 않습니다. 이 설정은 Univer 인스턴스 내 모든 단위에서 공유됩니다. `LocaleType.EN_US` 같은 `LocaleType` 값을 사용하세요.

* **모든 제품: UI**: `locale`은 메뉴, 도구 설명, 대화 상자와 플러그인 레이블의 번역을 바꿉니다. 사용자 콘텐츠나 기존 단위 이름은 바꾸지 않습니다.
* **Sheets: 셀 형식과 수식**: 숫자/날짜 표시는 숫자 형식의 locale 재정의, 통합 문서 스냅샷의 `locale`, 인스턴스의 `locale` 순서로 선택됩니다. `region`은 이를 대체하지 않습니다. `DOLLAR` 및 재무 함수 결과의 통화 형식과 한중일 입력 정규화는 계속 `locale`을 사용합니다.
* **Docs: 통계**: `locale`은 단어 분할과 단어 수 계산에 사용됩니다.

### 실행 중 언어 변경

언어를 변경하기 전에 설치된 플러그인 또는 프리셋의 언어 팩을 모두 로드하세요. `loadLocales()`는 번역을 병합하지만 언어를 바꾸지 않습니다. `setLocale()`은 언어를 선택하지만 팩을 다운로드하지 않습니다. 누락된 번역은 키 이름으로 표시됩니다. 다음 예제는 공통 UI 팩을 로드합니다. 다른 설치된 플러그인의 대상 언어 팩도 같은 호출에서 병합하세요.

```typescript
import { LocaleType, mergeLocales } from '@univerjs/core'
import UIEnUS from '@univerjs/ui/locale/en-US'

univerAPI.loadLocales(LocaleType.EN_US, mergeLocales(UIEnUS))
univerAPI.setLocale(LocaleType.EN_US)

console.log(univerAPI.getCurrentLocale()) // enUS
```

### 플러그인 모드에서 언어 팩 등록하기

플러그인 모드에서 언어 팩을 등록하려면 언어 팩을 제공하는 각 플러그인에서 해당 언어 팩을 가져온 뒤 하나의 객체로 병합하여 `Univer` 인스턴스에 전달해야 합니다. 다음은 그 예시입니다.

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import DesignEnUS from '@univerjs/design/locale/en-US' // [!code highlight]
import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US' // [!code highlight]
import UIEnUS from '@univerjs/ui/locale/en-US' // [!code highlight]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      DesignEnUS, // [!code highlight]
      UIEnUS, // [!code highlight]
      DocsUIEnUS, // [!code highlight]
    ),
  },
})
```

> [!WARNING: 주의]
> 모든 플러그인에 언어 팩이 포함되어 있는 것은 아닙니다. 각 기능의 문서에서 언어 팩 포함 여부를 안내합니다.

### 프리셋 모드에서 언어 팩 등록하기

프리셋 패키지에는 해당 플러그인의 언어 팩이 이미 포함되어 있으므로 프리셋에서 가져오기만 하면 됩니다.

```typescript
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'
import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US' // [!code highlight]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetDocsCoreEnUS, // [!code highlight]
    ),
  },
  presets: [
    UniverDocsCorePreset(),
  ],
})
```

### 언어 팩 병합

`mergeLocales` 메서드는 여러 플러그인 또는 프리셋의 언어 팩을 하나의 완전한 언어 팩 객체로 병합하는 데 사용합니다. 다음과 같이 사용할 수 있습니다.

#### 플러그인 모드

```typescript
import { mergeLocales } from '@univerjs/core'

// You can pass multiple language pack objects to merge
const locales = mergeLocales(
  plugin1Locales,
  plugin2Locales,
  presetLocales,
)
// You can also pass an array of language pack objects
const locales = mergeLocales([
  plugin1Locales,
  plugin2Locales,
  presetLocales,
])
```

#### 프리셋 모드

```typescript
import { mergeLocales } from '@univerjs/presets'

// You can pass multiple language pack objects to merge
const locales = mergeLocales(
  plugin1Locales,
  plugin2Locales,
  presetLocales,
)
// You can also pass an array of language pack objects
const locales = mergeLocales([
  plugin1Locales,
  plugin2Locales,
  presetLocales,
])
```

### 사용자 지정 언어 팩

Univer는 사용자 지정 언어 팩도 지원합니다. 필요에 따라 언어 팩 객체를 구성하여 `Univer` 인스턴스에 전달할 수 있습니다. 프리셋 언어 팩은 일반적으로 `<rootDir>/packages/<PLUGIN_NAME>/locale` 디렉터리에 저장됩니다.

```typescript
import { LocaleType, Univer } from '@univerjs/core'

const univer = new Univer({
  locale: LocaleType.JA_JP,
  locales: {
    [LocaleType.JA_JP]: {
      ui: {
        shortcut: {
          undo: '元に戻す',
          redo: 'やり直す',
        },
      },
    },
  },
})
```

### 번역 기여하기

Univer는 현재 다음과 같은 기본 제공 언어 팩을 지원합니다.

* `zh-CN`: 중국어 간체
* `en-US`: 영어
* `zh-TW`: 중국어 번체
* `zh-HK`: 중국어 번체(홍콩)
* `ru-RU`: 러시아어
* `vi-VN`: 베트남어
* `fa-IR`: 페르시아어
* `fr-FR`: 프랑스어
* `ja-JP`: 일본어
* `ko-KR`: 한국어
* `es-ES`: 스페인어
* `ca-ES`: 카탈루냐어
* `sk-SK`: 슬로바키아어
* `ar-SA`: 아랍어
* `de-DE`: 독일어
* `id-ID`: 인도네시아어
* `it-IT`: 이탈리아어
* `pl-PL`: 폴란드어
* `pt-BR`: 포르투갈어(브라질)

Univer는 포용성을 중시하는 오픈 소스 프로젝트로, 전 세계 개발자가 Univer의 로케일을 추가하거나 개선하는 데 참여하는 것을 환영합니다.

## 지역 설정

`region`은 지역별 기능에서 사용하는 지역 관례를 지정합니다. 이 설정은 Univer 인스턴스 내 모든 단위에서 공유됩니다.

두 설정 모두 `LocaleType` 값을 사용하세요. 예를 들어 `LocaleType.EN_US`의 값은 `enUS`이며 `en-US`는 언어 팩 파일 이름 / BCP 47 태그입니다. `region`에 `US`, `SG` 같은 국가 코드를 전달하지 마세요. UI가 다른 언어를 사용하면 지역에 해당하는 언어 팩을 추가로 로드할 필요가 없습니다.

`region`을 명시하지 않으면 이후의 `setLocale()` 호출을 포함하여 `locale`을 따릅니다. 초기화 시 `region`을 지정하거나 `setRegion()`을 호출하면 자동 추종이 중단되고 이후 언어를 바꿔도 지역은 유지됩니다. 자동 추종을 복원하는 공개 API는 없습니다. 함께 변경하려면 두 값을 모두 설정하세요.

`createUniver()` 또는 `new Univer()`의 `locale` 옆에 `region: LocaleType.DE_DE`를 추가하면 UI 언어를 유지하면서 독일의 지역 관례를 사용할 수 있습니다.

```typescript
import { LocaleType } from '@univerjs/core'

univerAPI.setRegion(LocaleType.DE_DE)
univerAPI.setLocale(LocaleType.EN_US)

console.log(univerAPI.getCurrentRegion()) // deDE
```

이 예제에서는 UI가 영어로 바뀌고 지역은 독일로 유지됩니다. `getCurrentLocale()`과 `getCurrentRegion()`은 현재 식별자를 반환합니다. 둘을 함께 변경하려면 동일한 `LocaleType` 값으로 두 setter를 호출하세요.

* **Sheets: 통화 작업**: `region`은 통화 도구 모음 아이콘, 통화/회계 형식 옵션과 미리 보기, 통화 명령이 적용하는 형식을 결정합니다. 기존 셀 형식을 다시 쓰거나 금액을 환산하지 않습니다.
* **Docs: 통계**: `region`은 통계 대화 상자와 상태 표시줄의 숫자 표시 형식(예: 자릿수 구분자)에 사용되며 계산 규칙을 바꾸지 않습니다.
* **스레드 댓글 활성화 시**: `region`은 날짜/시간 표시 형식을 결정하며 24시간제와 라틴 숫자를 사용합니다. `locale`은 댓글 UI 문구를 결정합니다. 저장된 타임스탬프는 변경되지 않으며 `region`은 시간대 설정이 아닙니다.
* **Boards, Slides, Bases, PDFs**: `locale`은 UI 번역을 제어합니다. `region`은 통합된 스레드 댓글 같은 공통 기능에서 사용할 수 있지만 보드/슬라이드 텍스트, Base 필드, PDF 콘텐츠의 형식을 자동으로 바꾸지 않습니다.

## 오른쪽에서 왼쪽으로 배치

> [!WARNING: 주의]
> 현재 RTL은 UI 계층만 지원하며 렌더링 계층은 지원하지 않습니다.

레이아웃 방향은 별도로 설정합니다. 초기화 시 `direction`을 지정하거나 `univerAPI.setDirection('rtl')` / `setDirection('ltr')`를 호출하세요. `locale` 또는 `region`만 바꿔서는 방향이 바뀌지 않습니다.

```typescript
univerAPI.setDirection('rtl')
```