CLI 구성 파일 생성(Strings)

컨텐츠는 영어 텍스트를 Phrase Language AI를 이용해 기계 번역한 것입니다.

필수 조건

API 액세스 토큰 (read write 범위 포함)
프로젝트 설정의 API 탭에 표시된 Strings 프로젝트 ID
들여쓰기를 포함한 기본적인 YAML 지식
리포지토리에서 CI로 phrase push 또는 phrase pull을 실행할 경우 Git 읽기 및 쓰기 권한

팁

더 자세한 정보는 Developer Hub를 참조하십시오.

구성 파일을 자동으로 생성하려면 다음 단계를 수행하십시오.

명령줄에서 phrase init를 입력하여 .phrase.yml 파일을 생성합니다.

구성 마법사가 CLI에서 시작됩니다.
다음을 제공합니다.
- 액세스 토큰
  
  $PHRASE_ACCESS_TOKEN을 사용하려면 붙여넣거나 Enter를 누르십시오.
- Strings 프로젝트 ID (예: abcdef1234567890abcdef1234567890)
- 로캘 파일 형식 (예: json, rails_yaml, ios_strings)
- 로컬 경로
  
  프로젝트 코드베이스 내 로캘 파일에 대한 Glob 또는 정확한 경로 (예: config/locales/*.json)

기본 .phrase.yml 파일이 현재 디렉터리에 생성됩니다.

팁

마법사를 완전히 건너뛰려면 플래그를 제공하십시오. 예: phrase init --access_token=$PHRASE_ACCESS_TOKEN --project_id=... --file_format=ios_strings --path='ios/*.strings'.

수동으로 생성 또는 복사된 구성 파일을 사용하는 경우 다음 중 하나의 위치에 놓습니다.

CLI 클라이언트가 호출되는 현재 작업 디렉터리(pwd).
현재 사용자의 홈 디렉터리(Unix의 $HOME, Windows의 $HomePath)
PHRASEAPP_CONFIG 환경 변수에 지정된 경로
--config 플래그를 통한 구성 파일 경로(예: /some/path/to/phrase.yml)

CLI 옵션 개요

샘플 구성 파일

전역 설정

키	유형	필수	설명
`phrase.access_token`	문자열	예	개인 액세스 토큰.
`phrase.project_id`	문자열	예	Strings 프로젝트 설정에 표시된 공개 프로젝트 ID.
`phrase.file_format`	문자열	예	기본 로캘 파일 형식 (API 확장).
`phrase.locale_mapping`	객체	아니요	`<locale_name>` 자리 표시자를 사용하여 파일 경로에 사용할 수 있도록 Phrase 로캘 ID를 사용자 지정 이름에 매핑합니다. 이는 Android와 같이 표준이 아닌 명명 규칙을 사용하는 플랫폼에 유용합니다. 매핑에 로캘이 지정되지 않은 경우, 기본적으로 표준 Phrase 로캘 이름이 사용됩니다.

푸시: 소스

키	유형	필수	설명
`push.sources[].file`	경로	예	푸시할 파일의 상대 경로(예: `./path/to/file/<locale_code>.json`). `<locale_name>`, `<locale_code>`, `<tags>`을(를) 지원합니다.
`push.sources[].project_id`	문자열		이 특정 파일 소스에 대해 전역 `프로젝트 ID`을(를) 재정의합니다. 동일한 구성 파일에서 여러 Phrase 프로젝트로 파일을 푸시할 때 유용합니다.

푸시: 매개변수

매개변수	유형	기본값	설명
`file_format`	문자열	헤더	이 소스에 대한 파일 형식을 재정의합니다.
`locale_id`	문자열	—	로캘 이름(예: `en-US`) 또는 공용 로캘 ID.
`tags`	문자열	—	새 키에 대한 쉼표로 구분된 태그.
`update_translations`	부울	`false`	파일 콘텐츠로 기존 번역을 업데이트합니다.
`update_translation_keys`	부울	`true`	새 키가 생성되거나 기존 키가 업데이트되는 것을 방지하려면 여기에 `false`을(를) 전달하십시오.
`update_descriptions`	부울	`false`	키 설명을 업데이트합니다. 비어 있음 설명은 기존 설명을 덮어씁니다.
`skip_upload_tags`	부울	`false`	업로드 태그가 생성되지 않았습니다.
`skip_unverification`	부울	`false`	업데이트된 번역은 확인되지 않음 상태가 아닙니다.
`file_encoding`	문자열	—	파일 인코딩: `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE` 또는 `ISO-8859-1`.
`locale_mapping`	객체	—	(Excel/CSV 전용) 로캘 코드를 열 이름에 매핑합니다(예: 번역 구문 분석을 위해 `{"en": "C", "de": "D"}` 사용). 이는 파일 경로에 사용되는 최상위 `locale_mapping`과는 다릅니다.
`autotranslate`	부울	`false`	업로드된 언어에 대한 번역을 자동으로 가져옵니다.
`mark_reviewed`	부울	`false`	가져온 번역을 검토됨으로 표시합니다(고급 검토 워크플로가 활성화되어 있어야 함).

Push: 형식 옵션

모든 사용 가능한 형식 옵션은 CLI 구성에서 지원됩니다. 예시는 샘플 구성 파일을 참조하십시오.

Pull: 대상

키	유형	필수	설명
`pull.targets[].file`	경로	예	가져온 로캘 파일의 상대 경로(예: `./Radio.de/<locale_code>.lproj/Localizable.Strings`).
`pull.targets[].project_id`	문자열		이 특정 Pull 대상에 대해 전역 `project_id<1>을(를) 재정의합니다. 동일한 구성 파일을 사용하여 여러 Phrase 프로젝트에서 번역을 가져오는 기능을 활성화합니다.`

Pull: 매개변수

매개변수	유형	기본값	설명
`file_format`	문자열	—	`Strings`이어야 합니다.
`locale_id`	문자열	—	로캘 이름(예: `en-US`) 또는 공용 로캘 ID.
`tags`	문자열	—	가져올 키를 필터링하기 위한 쉼표로 구분된 태그입니다.
`include_empty_translations`	부울	`false`	번역이 없는 키를 포함합니다.
`exclude_empty_zero_forms`	부울	`false`	비어 있는 경우 0형식 복수형을 제외합니다.
`include_translated_keys`	부울	`true`	이미 번역이 있는 키를 포함합니다.
`keep_notranslate_tags`	부울	`false`	`[NOTRANSLATE]` 태그를 아웃풋에 보존합니다.
`encoding`	문자열	—	파일 인코딩: `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE` 또는 `ISO-8859-1`.
`include_unverified_translations`	부울	`true`	`false`인 경우, 확인되지 않음 번역을 제외합니다.
`use_last_reviewed_version`	부울	`false`	`true`인 경우, 마지막으로 검토됨 버전을 사용합니다(고급 검토 워크플로 필요).
`fallback_locale_id`	문자열	—	누락된 번역에 사용할 대체 로캘입니다.

가져오기: 형식 옵션

모든 사용 가능한 형식 옵션은 CLI 구성에서 지원됩니다. 예시는 샘플 구성 파일을 참조하십시오.

다중 구성

모노레포에서는 각 패키지에 구성 파일을 하나씩 배치하고 해당 하위 폴더에서 CLI를 실행하거나, --config 옵션을 사용하여 CI 작업을 다른 구성 파일로 지정하십시오.

Git 통합

GitLab:

.phrase.yml 구성 파일은 리포지토리에 있어야 합니다. 이 파일은 리포지토리로부터 가져오기(pull) 또는 내보내기(push)할 파일을 정의합니다.
리포지토리에 대한 읽기 및 쓰기 액세스 권한이 필요합니다.
잘못 정의된 구성 파일은 오류를 일으킬 수 있습니다. 파일에 하나 이상의 push 및 pull 대상이 있는지, 파일 형식이 올바른지, update_translations 매개 변수의 설정이 올바른지 확인하십시오.
GitLab 9.5 이상을 사용하면 API가 호환됩니다.

GitHub:

.phrase.yml 구성 파일은 리포지토리에 있어야 합니다. 이 파일은 리포지토리로부터 가져오기(pull) 또는 내보내기(push)할 파일을 정의합니다.
리포지토리에 대한 읽기 및 쓰기 액세스 권한이 필요합니다.
잘못 정의된 구성 파일은 오류를 일으킬 수 있습니다. 파일에 하나 이상의 push 및 pull 대상이 있는지, 파일 형식이 올바른지, update_translations 매개 변수의 설정이 올바른지 확인하십시오.
리포지토리의 범위에 대한 GitHub 액세스 토큰(공용 리포지토리와 동기화하는 경우 public_repo).
GitHub에서 SSO가 활성화된 경우 액세스 토큰에 대해서도 활성화해야 합니다.
phrase_translations 분기가 보호되지 않습니다.
리포지토리 설정에 서명된 커밋이 필요하지 않은지 확인하십시오.

BitBucket:

.phrase.yml 구성 파일은 리포지토리에 있어야 합니다. 이 파일은 리포지토리로부터 가져오기(pull) 또는 내보내기(push)할 파일을 정의합니다.
리포지토리에 대한 읽기 및 쓰기 액세스 권한이 필요합니다.
잘못 정의된 구성 파일은 오류를 일으킬 수 있습니다. 파일에 하나 이상의 push 및 pull 대상이 있는지, 파일 형식이 올바른지, update_translations 매개 변수의 설정이 올바른지 확인하십시오.