> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Bộ điều hợp Crowdin

> Cấu hình Crowdin cho chế độ đồng bộ gốc hoặc chế độ tệp tương thích với Crowdin.

## Hai quy trình làm việc của Crowdin

Hyperlocalise hiện hỗ trợ hai tích hợp Crowdin khác nhau:

1. Chế độ đồng bộ gốc với `i18n.yml` cộng với `sync push` / `sync pull`
2. Chế độ tệp tương thích với Crowdin cùng với `crowdin.yml` và `hyperlocalise crowdin ...`

Sử dụng chế độ đồng bộ gốc khi bạn muốn đồng bộ mục do Hyperlocalise quản lý.

Sử dụng chế độ tệp khi bạn muốn một giải pháp thay thế sát hơn để thay thế trực tiếp cho các quy trình làm việc với tệp của Crowdin CLI.

## Chế độ đồng bộ gốc

### Cấu hình bắt buộc

```jsonc theme={null}
{
  "storage": {
    "adapter": "crowdin",
    "config": {
      "projectID": "123456",
      "apiTokenEnv": "CROWDIN_API_TOKEN"
    }
  }
}
```

### Crowdin Enterprise

Đặt `apiBaseURL` khi không gian làm việc của bạn sử dụng Crowdin Enterprise thay vì API Crowdin Cloud mặc định.

```jsonc theme={null}
{
  "storage": {
    "adapter": "crowdin",
    "config": {
      "projectID": "123456",
      "apiTokenEnv": "CROWDIN_API_TOKEN",
      "apiBaseURL": "https://example.api.crowdin.com"
    }
  }
}
```

### Các trường cấu hình tùy chọn

* `apiBaseURL`: Ghi đè URL cơ sở API của Crowdin. Dùng tùy chọn này cho Crowdin Enterprise.
* `sourceLanguage`
* `targetLanguages`
* `timeoutSeconds`

## Chế độ tệp tương thích với Crowdin

Sử dụng `crowdin.yml` hoặc `crowdin.yaml`.

Ví dụ:

```yaml theme={null}
project_id_env: CROWDIN_PROJECT_ID
api_token_env: CROWDIN_PERSONAL_TOKEN
preserve_hierarchy: true

files:
  - source: /src/messages.json
    translation: /locales/%locale%/%original_file_name%
    export_only_approved: true
```

Các trường `crowdin.yml` được hỗ trợ trong v1:

* `project_id`
* `project_id_env`
* `api_token`
* `api_token_env`
* `base_url`
* `base_url_env`
* `base_path`
* `base_path_env`
* `branch`
* `preserve_hierarchy`
* `files[].source`
* `files[].translation`
* `files[].languages_mapping`
* `files[].excluded_target_languages`
* `files[].skip_untranslated_strings`
* `files[].skip_untranslated_files`
* `files[].export_only_approved`

Sử dụng giao diện CLI tương thích:

```bash theme={null}
hyperlocalise crowdin init
hyperlocalise crowdin config validate
hyperlocalise crowdin upload sources
hyperlocalise crowdin upload translations --language fr
hyperlocalise crowdin download --language fr --export-only-approved --skip-untranslated-strings
hyperlocalise crowdin download --language fr --merge-approved
hyperlocalise crowdin download --language fr --include-sources
```

`--merge-approved` hợp nhất các khóa đối tượng JSON đã được phê duyệt vào các tệp dịch cục bộ hiện có và bảo toàn các khóa cục bộ bị bỏ qua khỏi bản xuất đã được phê duyệt của Crowdin.
Khi Crowdin bao gồm các giá trị dự phòng của ngôn ngữ nguồn trong bản xuất đó, Hyperlocalise sẽ bỏ qua những giá trị vẫn khớp với JSON nguồn để các chuỗi nội bộ đã được dịch trước đó được giữ nguyên.

`--include-sources` cũng tải các tệp nguồn Crowdin khớp xuống các đường dẫn `files[].source` đã cấu hình trước khi ghi bản dịch. Các đường dẫn nguồn chính xác có thể được tạo cục bộ nếu còn thiếu; các đường dẫn nguồn theo glob bị giới hạn ở những tệp khớp với phần mở rộng glob cục bộ.

Sử dụng root `branch:` trong `crowdin.yml` hoặc truyền `--branch <name>` để tải lên và tải xuống các tệp từ một nhánh Crowdin. Cờ này ghi đè giá trị cấu hình cho lệnh đó.

Xác thực sẽ thất bại theo mặc định an toàn đối với các trường hoặc lệnh Crowdin không được hỗ trợ.

## Các vấn đề thường gặp

* không tìm thấy token: export `CROWDIN_API_TOKEN`
* Yêu cầu API Enterprise bị lỗi: xác minh `storage.config.apiBaseURL` trỏ đến máy chủ API Enterprise của bạn và sử dụng `https`
* lỗi tra cứu dự án: kiểm tra ID dự án và quyền tài khoản
* cập nhật từng phần: xem báo cáo xung đột với `--output json`
* lỗi xác thực chế độ tệp: hãy xóa các trường `crowdin.yml` không được hỗ trợ hoặc chuyển sang chế độ đồng bộ `i18n.yml` gốc