구성 · 리소스 번역기

기본 위치가 아니면 configPath 입력으로 경로를 덮어쓰세요.

스키마

# .github/resource-translator.yml
sourceLocale: en

# Provider config can be nested. Keep secrets in workflow inputs; use repo
# config for non-secret defaults like region, model, formality, or category.
provider:
  azure:
    categoryId: my-custom-translator-category
    apiVersion: "3.0"
    allowFallback: true

toLocales:
  - fr
  - de
  - es
include:
  - "src/**/*.en.json"
  - "apps/**/*.en.resx"
exclude:
  - "**/__tests__/**"
glossary:
  Acme: Contoso
  Octocat: Octocat   # keep brand names verbatim

# Translator request shape — most users can ignore these.
textType: plain                  # plain | html
profanityAction: NoAction        # NoAction | Marked | Deleted
profanityMarker: Asterisk        # Asterisk | Tag (only when profanityAction == Marked)

# Resilience — Translator returns 429 under load. Defaults are usually
# fine; tune only if your runs are large enough to hit them.
maxRetries: 5
retryBackoffMs: 30000             # cap on any single backoff sleep (ms)

# Placeholder protection. ON by default — wraps tokens like {{name}},
# {0}, %s, ${var} into sentinels before translation and restores them
# on the way back. Set false only when source intentionally contains
# placeholder-shaped literals.
protectPlaceholders: true
customPlaceholderPatterns:
  - "<<.+?>>"                     # any extra token syntax you use

# Per-key opt-out. Keys matching any glob are dropped from the request
# and pass through with the source value preserved.
noTranslatePatterns:
  - "errors.code.*"
  - "brands.*"

현장 참조

provider

유형: "azure" | "aws" | "google" | provider block

Either a provider string or a nested provider block (provider.azure, provider.aws, or provider.google). Prefer nested blocks for provider-specific settings; keep secrets in workflow inputs rather than committed config.

sourceLocale

유형: string

설정하지 않으면 sourceLocale 입력으로 다시 돌아가요. 또한 짧은 문자열이 자동 감지되지 않도록 Translator로 from=<locale> 전달했습니다.

toLocales

유형: string[]

배열이나 쉼표로 구분된 문자열 중 하나일 수 있습니다.

include / exclude

유형: string[]

글롭 패턴은 절대 경로와 작업 공간 상대 경로에 대해 평가되었습니다.

glossary

유형: map<string,string>

번역 후 용어가 무효화됩니다. 단어 경계 인식(C++, .NET 처리).

categoryId

유형: string

Azure Custom Translator 카테고리 — 산업/도메인 노브(법률, 의료, 마케팅 톤 등)입니다. ?category=...로 보냈습니다.

textType

유형: "plain" | "html"

기본값은 plain입니다. 리소스 값에 실제 HTML 조각이 포함되어 있을 때만 html 사용하세요.

profanityAction

유형: "NoAction" | "Marked" | "Deleted"

번역된 결과물에서 욕설을 어떻게 다룰 것인가.

profanityMarker

유형: "Asterisk" | "Tag"

"Marked" profanityAction 때만 의미가 있습니다.

allowFallback

유형: boolean

false 설정해 categoryId가 대상 로케이지에 배포되지 않을 때 변환 실패로 설정하세요. 일반 모델로 되돌아가는 대신에요.

apiVersion

유형: string

번역기 REST API 버전. 기본값은 3.0입니다.

awsFormality

유형: "FORMAL" | "INFORMAL"

AWS Translate formality setting for supported target languages.

awsBrevity

유형: boolean

Set to true to enable AWS Translate brevity mode for supported language pairs.

awsTerminologyNames / awsParallelDataNames

유형: string[]

AWS Translate custom terminology and parallel data resource names. Either an array or comma-separated string.

googleModel

유형: string

Google Cloud Translation model, e.g. nmt or base.

googleApiEndpoint

유형: string

Optional Google Cloud Translation API endpoint override.

googleAutoRetry

유형: boolean

Optional Google Cloud Translation automatic retry toggle. Leave unset to use the Google client default.

maxRetries

유형: integer

일시적인 HTTP 응답에 대한 최대 재시도 횟수(408, 425, 429, 500, 502, 503, 504). 기본값은 5. 요청당 총 HTTP 호출은 1 + maxRetries입니다.

retryBackoffMs

유형: integer

어떤 단일 백오프 수면에도 캡(ms)을 설정하세요. 기본값은 30000입니다. Azure의 Retry-After 머리는 존재할 때 정확히 존중됩니다; 그렇지 않으면 지터된 지수 백오프가 사용되며, 이 값으로 제한됩니다.

protectPlaceholders

유형: boolean

기본값은 true입니다. 활성화되면 {{name}}, ${var}, {0}, {0:N2}, %s, %1$s, HTML 엔티티와 같은 토큰이 변환 전에 센티넬 토큰으로 대체되고 변환 후에는 복원됩니다. 소스가 의도적으로 자리 표시자 모양의 리터럴을 포함할 때만 비활성화하세요.

customPlaceholderPatterns

유형: string[]

기본 자리 표시자 집합에 추가된 추가 정규 표현 패턴(예: <<.+?>> 사용자 지정 토큰 구문을 위한 것). 유효하지 않은 정식은 무시합니다.

noTranslatePatterns

유형: string[]

글롭 패턴은 파서 레벨 키(JSON 점선 경로, RESX name, PO msgid, XLIFF 단위 id, INI/restext 키)와 일치합니다. 일치하는 키는 요청에서 제외되고 소스 값이 보존된 상태로 통과됩니다.

changeDetection

유형: "smart" | "disabled"

Defaults to smart. Uses the committed state manifest to translate only changed or missing parser keys. Set to disabled or false to preserve the legacy always-translate behavior.

statePath

유형: string

Path to the deterministic smart change-detection state manifest. Defaults to .github/resource-translator-state.json.

적재 순서

이 액션은 워크플로우에서 명시적인 입력을 읽습니다.
configPath에서 YAML 설정을 불러와요.
모든 필드가 공유될 때마다, 입력이 승리합니다; 그렇지 않으면 YAML 값을 사용합니다.
병합된 값들이 검증됩니다. 유효하지 않은 열거(예: profanityAction: Mask)는 행동이 빠르게 실패하고 메시지가 명확하게 전달됩니다.

간단히 말해, 톤과 인내심을 말해줍니다

Azure AI Translator v3 API에는 단일 톤 노브가 없습니다. 두 가지 설정을 결합하면 대부분의 제어가 가능합니다:

산업 / 분야: categoryId 사용해 자신의 말뭉치로 학습된 Azure Custom Translator 카테고리를 가리키세요 — 법률, 기술, 의료, 마케팅 등 어떤 분야든 말입니다. 이것이 톤, 브랜드 목소리, 어휘를 결정하는 가장 강력한 지렛대입니다.
표면 텍스트: 용어집를 사용해 브랜드명과 제품 용어를 그대로 잠가고, 젊은 층을 위한 현지화 타겟팅 시 profanityAction 욕설을 삭제하세요.

언어를 선택하세요

저장소 구성

스키마

현장 참조

적재 순서

간단히 말해, 톤과 인내심을 말해줍니다