고급 사용자 정의 옵션

이 페이지는 HTML/CSS/JSON에 어느 정도 익숙한 고급 사용자를 위한 안내입니다. 고급 설정을 활용하면 적응력을 크게 높일 수 있지만, "겉보기엔 맞는 것 같으나 실제로는 반영되지 않는" 구성을 작성할 가능성도 커지므로, 설정 변경 전 반드시 백업을 권장합니다.

사용 전 안내

진입점: 개발자 설정
User Config / User Rules 를 편집하기 전 백업하세요. 포맷 오류로 인해 설정이 무시될 수 있습니다.
최종 내장 구성은 "Click to expand the final config" 기준으로 확인하세요 (필드, 기본값, 사용 가능한 서비스 등).

진입점과 우선순위

주요 진입점 (개발자 설정):

Edit Full User Config: rules, 번역 서비스, 스타일 등 전체 설정
Edit User Rules: rules 배열만 수정 ({ "rules": [...] } 형태로 감싸지 마세요. 배열만 입력)
Injected CSS: 전체 CSS 추가

우선순위 (높음 → 낮음): 조건에 부합하는 rules > generalRule > 내장 기본 설정
특정 rule이 적용되면, generalRule과 병합되어 해당 rule의 필드가 우선합니다.

빠른 시작 (가장 흔한 요구)

1) 특정 사이트의 본문만 번역하기

{
  "rules": [
    {
      "matches": ["example.com"],
      "selectors": ["article", ".post-content"],
      "excludeSelectors": ["nav", "footer", ".comment"]
    }
  ]
}

2) 항상 번역 / 아예 번역 안 함

{
  "translationUrlPattern": {
    "matches": ["stackoverflow.com"],
    "excludeMatches": ["www.google.com/mail/*"]
  }
}

3) 사이트별로 번역 엔진 다르게 사용하기

{
  "translationService": "google",
  "translationServices": {
    "deepl": {
      "matches": ["sci-hub.se"]
    }
  }
}

4) 사이트별 번역 결과 스타일 지정

{
  "translationTheme": "none",
  "translationThemePatterns": {
    "underline": {
      "matches": ["discord.com"]
    }
  }
}

5) 번역으로 인해 스타일이 이상해졌을 때 스타일 수정

{
  "rules": [
    {
      "matches": ["youtube.com"],
      "globalStyles": {
        "#video-title": "max-height:unset;"
      }
    }
  ]
}

6) 미설정된 번역 서비스를 메뉴에 표시하지 않음

{
  "showUnconfiguredTranslationServiceInPopup": false
}

규칙과 매칭

규칙 병합

generalRule: 모든 사이트에 통용되는 기본 규칙
rules: 사이트별 규칙. 조건 만족 시 최우선 적용

rules 내에서 generalRule 대부분의 필드를 활용 가능합니다.

matches 의 일반적인 형태

matches는 문자열 또는 배열 지원:

도메인: example.com
전체 URL: https://example.com/path/
와일드카드: https://*/*q=*
전체매칭: * / *://* / *://*/*
로컬 파일: file://*

주의: *.twitter.com은 하위 도메인만 포함하며, twitter.com 루트는 미포함입니다.

selectors / excludeSelectors

selectors: 지정 요소만 번역 (기본 범위 덮어씀)
excludeSelectors: 지정 요소는 번역에서 제외

기본 범위에 추가/제거만 하고 싶다면 .add/.remove 사용 권장 (다음 항목 참고)

상속과 증분 수정 (.add / .remove)

배열/객체 필드는 .add/.remove 형태로 증분 수정이 지원됩니다.
기본 규칙 덮어쓰기를 피하려면 권장 방법입니다.

[
  {
    "id": "twitter",
    "selectors.add": ["[data-testid='tweetText'] a"],
    "excludeSelectors.add": ["header"]
  }
]

주요 필드 (발췌)

매칭 관련:

matches / excludeMatches
selectorMatches / excludeSelectorMatches

번역 범위:

selectors / excludeSelectors / excludeTags
stayOriginalSelectors / stayOriginalTags
extraInlineSelectors / extraBlockSelectors

스타일 및 레이아웃:

translationClasses: 번역에 추가 클래스 설정
globalStyles / globalAttributes
injectedCss / additionalInjectedCss
wrapperPrefix / wrapperSuffix
blockMinTextCount / blockMinWordCount

타이밍과 모바일:

urlChangeDelay / observeUrlChange
isShowUserscriptPagePopup

GPT 류 스트리밍 채팅 번역

{
  "matches": ["chat.openai.com"],
  "excludeSelectors": [".markdown *"],
  "aiRule": {
    "streamingSelector": ".result-streaming.markdown",
    "messageWrapperSelector": ".markdown",
    "streamingChange": true
  }
}

필드별 더 자세한 설명은 마지막 "부록: Rule 필드 참고" 참고

matches 매칭 로직 (간단 설명)

순수 도메인 (* 또는 경로 없음): hostname 기준 비교
전체 URL(* 없음): 프로토콜 + 호스트 + 포트 + 경로 일치 시 매칭
* 포함 또는 프로토콜 생략: 와일드카드 규칙 적용 (기본적으로 http/https/file 지원)

자주 쓰는 예시:

twitter.com → https://twitter.com/home 매칭 O
*.twitter.com → https://mobile.twitter.com 매칭 O, https://twitter.com 매칭 X
https://twitter.com/home → 해당 경로만 일치
twitter.com/* → twitter.com 하위 전체

사이트 적용 예시 (Twitter)

아래는 Twitter 내장 규칙 (발췌) 이며, selectors / excludeSelectors / globalStyles 전형적 활용법입니다.

[
  {
    "id": "twitter",
    "matches": [
      "twitter.com",
      "mobile.twitter.com",
      "tweetdeck.twitter.com",
      "pro.twitter.com",
      "https://platform.twitter.com/embed*"
    ],
    "selectors": [
      "[data-testid=\"tweetText\"]",
      ".tweet-text",
      ".js-quoted-tweet-text",
      "[data-testid='card.layoutSmall.detail'] > div:nth-child(2)",
      "[data-testid='developerBuiltCardContainer'] > div:nth-child(2)",
      "[data-testid='card.layoutLarge.detail'] > div:nth-child(2)",
      "[data-testid='cellInnerDiv'] div[data-testid='UserCell'] > div> div:nth-child(2)",
      "[data-testid='UserDescription']",
      "[data-testid='HoverCard'] div[dir=auto]",
      "[data-testid='HoverCard'] span[dir=auto]",
      "[data-testid='HoverCard'] [role='dialog'] div[dir=ltr]",
      "[data-testid='birdwatch-pivot'] div[dir=ltr]"
    ],
    "excludeSelectors": [
      "[aria-describedby][role=button]",
      "header",
      "[data-testid='radioGroupplayback_rate'] div",
      "[data-testid='userFollowIndicator']",
      "[class='css-901oao r-14j79pv r-37j5jr r-n6v787 r-16dba41 r-1cwl3u0 r-bcqeeo r-qvutc0']",
      "[class='css-175oi2r r-1wbh5a2 r-dnmrzs']"
    ],
    "globalStyles": {
      "[data-testid='card.layoutLarge.detail'] > div:nth-child(2)": "-webkit-line-clamp: unset;",
      "[data-testid='card.layoutSmall.detail'] > div:nth-child(2)": "-webkit-line-clamp: unset;",
      "[data-testid='tweetText']": "-webkit-line-clamp: unset;"
    }
  }
]

selectors: 트윗 본문 등 중심 내용만 번역, 닉네임/버튼 등은 번역 X
excludeSelectors: 버튼·네비게이션 등 인터랙션 요소 번역 미적용
globalStyles: 줄수 제한 해제, 번역이 잘리는 현상 방지

사용자 정의 사이트 적용

id로 내장 규칙을 상속하고, .add/.remove로 증분 수정 가능

[
  {
    "id": "twitter",
    "selectors.remove": ["[data-testid=\"tweetText\"]"],
    "selectors.add": ["[data-testid=\"tweetText\"] a"],
    "excludeSelectors.add": ["header"],
    "excludeSelectors.remove": []
  }
]

설명:

id로 내장 규칙을 상속하여 불필요한 matches 작성 불필요
.add/.remove로 배열 필드 증분 수정, 적극 권장됨

주요 내장 id(발췌)

isEbook: epub 리더 페이지
isEbookBuilder: epub 번역본 생성 페이지
pdf: PDF 번역 대조 페이지

전체 내장 규칙:

https://github.com/immersive-translate/next-immersive-translate/blob/main/docs/buildin_config.json

번역 서비스 설정

translationService: 기본 번역 엔진
translationServices: 서비스 설정 및 사이트별 덮어쓰기
showUnconfiguredTranslationServiceInPopup: 미설정 서비스 숨김

예시 (텐센트 번역):

{
  "translationService": "tencent",
  "translationServices": {
    "tencent": {
      "secretId": "xxx",
      "secretKey": "xxx",
      "matches": ["twitter.com"],
      "limit": 3,
      "maxTextGroupLengthPerRequest": 25,
      "maxTextLengthPerRequest": 1800,
      "apiUrl": ""
    }
  }
}

설명:

matches: 해당 서비스가 적용될 사이트 지정
limit: 서비스별 초당 최대 요청수 제한
maxTextGroupLengthPerRequest / maxTextLengthPerRequest: 1 회 요청 규모 제한
apiUrl: 엔드포인트 수동 지정 가능

요청 타임아웃 설정 (최대 대기시간)

서비스별로 요청 타임아웃 (ms 단위) 설정 가능. Pro 서비스는 proRequestTimeout 개별 적용

{
  "translationServices": {
    "openai": {
      "requestTimeout": 60000
    },
    "gemini": {
      "proRequestTimeout": 90000
    }
  }
}

참고:

너무 길면 번역 대기 시간 증가, 짧으면 자주 실패 가능
서비스별 기본값은 다르며 최종 구성 참고
proRequestTimeout은 provider가 pro일 때만 반영 (유료 서비스)

언어 및 번역 전략

항상 번역 / 번역 금지 언어 설정

{
  "translationLanguagePattern": {
    "matches": ["en"],
    "excludeMatches": ["zh"]
  }
}

특정 사이트에 소스 언어 지정

{
  "sourceLanguageUrlPattern": {
    "en": {
      "matches": ["*.google.com"]
    }
  }
}

기타 자주 쓰이는 글로벌 설정

번역문에서 HTML 태그 렌더링 허용

번역 결과에 HTML 태그가 포함되어야 할 때 사용

{
  "enableRenderHtmlTag": true
}

번역 스타일 및 테마

translationTheme에서 지원하는 스타일 (최종 구성 기준):

none, grey, dashed, dashedBorder, solidBorder, dotted, underline, mask, opacity,
paper, dividingLine, highlight, marker, marker2, blockquote, weakening, italic,
bold, thinDashed, nativeDotted, wavy, nativeDashed, nativeUnderline, background

사이트별 테마 지정 예시:

{
  "translationThemePatterns": {
    "highlight": {
      "matches": ["discord.com"]
    }
  }
}

AI / 고급 서비스 파라미터

다음 고급 설정은 개발자 설정 -> Edit Full User Config에 추가할 수 있습니다.

무료 AI 번역 모드

확장 프로그램은 이제 무료 AI 통합 번역 서비스를 지원합니다. 이 모드를 활성화하면 무료 AI 통합 번역 경로가 우선 사용됩니다.

현재 제한 사항:

AI 용어집은 아직 지원되지 않습니다
AI 사용자 지정 프롬프트는 아직 지원되지 않습니다

이 모드를 끄고 이전의 비통합 무료 AI 번역 방식으로 되돌리려면 다음 설정을 추가하세요.

{
  "enableFreeModelMode": false
}

temperature

{
  "translationServices": {
    "openai": {
      "temperature": 0.2
    }
  }
}

사용자 정의 요청 헤더·바디

{
  "translationServices": {
    "claude": {
      "headerConfigs": {
        "anthropic-version": "2023-06-01",
        "anthropic-dangerous-direct-browser-access": "true"
      },
      "bodyConfigs": {
        "max_tokens": 2048
      }
    }
  }
}

Gemini 계열 모델 사용자 정의 설정

Gemini 계열은 기본 설정이 내장되어 있으므로, 덮어쓰기 시 modelsOverrides를 권장

{
  "translationServices": {
    "gemini": {
      "modelsOverrides": [
        {
          "models": ["gemini-2.5-flash", "gemini-2.5-flash-lite"],
          "bodyConfigs": {
            "temperature": 0.1
          }
        }
      ]
    }
  }
}

참고: modelsOverrides는 다른 AI 서비스에도 적용 가능. 모델명 기준으로 해당 설정이 덮어써집니다.

사용자 정의 프롬프트 완전 준수

대형 언어 모델의 "환각 (hallucination)" 문제를 줄이기 위해, 플러그인은 번역 품질 검증 로직을 내장하고 있습니다. 요청과 응답의 Token 수 비율이 정상인지 자동 판별하여 비정상 (너무 높거나 낮은 경우) 시 해당 결과 무효화 및 대체 서비스로 전환됩니다.
프롬프트가 단순 번역이 아닌 확장/교정 등이라면 Token 비율이 기준 미달일 수 있으므로, 이 때 "strictPrompt" 모드를 켜면 검증을 생략합니다.

{
  "translationServices": {
    "claude": {
      "strictPrompt": true
    }
  }
}

다국어 프롬프트 커스텀 (부분 예시)

{
  "translationServices": {
    "openai": {
      "langOverrides": [
        {
          "id": "auto2ja",
          "systemPrompt": "あなたはプロの翻訳エンジンです。",
          "prompt": "次のテキストを{{to}}に翻訳してください：\n\n<text>\n{{text}}\n</text>",
          "multiplePrompt": "<yaml>\n{{yaml}}\n</yaml>",
          "subtitlePrompt": "<yaml_subtitles>\n{{yaml}}\n</yaml_subtitles>"
        }
      ]
    }
  }
}

용어집 & 기계 번역

최신 AI 용어집 기능은 AI 번역 엔진에 한해 적용됩니다.

기계 번역은 기본적으로 용어집 미적용 (플레이스홀더 치환 방식으로 품질 저하 우려), 반드시 필요할 시 강제 활성화 가능 (비권장):

{
  "enableMachineTranslateTerms": true
}

캐시 자동 정리 주기

기본적으로 30 일마다 번역 캐시가 자동 삭제되어 성능 저하를 예방합니다.

{
  "cacheMaxAgeDay": 30
}

Injected CSS 와 globalStyles 의 차이

Injected CSS: 전체 페이지 단위로 CSS 일괄 추가 (사이트 일괄 수정에 적합)
globalStyles: 규칙 단위 스타일 덮어쓰기 (사이트별 부분 수정에 적합)

Injected CSS 예시:

.immersive-translate-target-wrapper img {
  width: 16px;
  height: 16px;
}

디버깅 및 흔한 실수

*.twitter.com은 루트 도메인에 적용 안 됨 → twitter.com도 꼭 함께 작성
selectors 사용 시 기본 번역 범위가 덮어써짐 → 증분 변경은 .add/.remove 사용 우선
matches에 example.com/path처럼 경로 입력 시, 와일드카드 적용됨 (정확한 패턴인지 확인)
반영이 안 될 때: 최종 구성 결과 확인 → 새로고침
JSON 의 마지막 콤마 (,) 는 오류 원인!

부록: Rule 필드 참고

아래는 Rule 인터페이스 필드 (문서 버전) 이며, 자주 쓰는 속성을 위주로 정리.
전체/최신 필드는 실제 설정에서 최종 참고 바랍니다.
배열·객체 필드는 .add/.remove 증분 수정으로 덮어쓰기 방지 가능!

export interface Rule {
  // 사이트 매칭
  id?: string; // 내장 규칙 ID, 내장 규칙 상속 시
  matches?: string | string[]; // 해당 Rule 이 적용될 사이트
  excludeMatches?: string | string[]; // 제외할 사이트
  selectorMatches?: string | string[]; // URL 없이 셀렉터로 직접 매칭
  excludeSelectorMatches?: string | string[]; // 셀렉터 매칭 제외 규칙

  // 번역 범위 지정
  selectors?: string | string[]; // 지정 요소만 번역
  excludeSelectors?: string | string[]; // 지정 요소 번역 제외
  excludeTags?: string | string[]; // 해당 태그 번역 제외

  // 번역 범위 추가 (실패 시 selectors.add / selectors.remove 사용)
  additionalSelectors?: string | string[]; // 번역 범위 추가
  additionalExcludeSelectors?: string | string[]; // 번역 제외 추가
  additionalExcludeTags?: string | string[]; // 태그 제외 추가 (일부 버전에서 미지원)

  // 원본 유지
  stayOriginalSelectors?: string | string[]; // 해당 요소는 원본 노출
  stayOriginalTags?: string | string[]; // 해당 태그 원본 유지 (예: code)

  // Block 또는 Inline
  extraBlockSelectors?: string | string[]; // 블록으로 간주할 셀렉터
  extraInlineSelectors?: string | string[]; // 인라인 요소로 간주할 셀렉터
  inlineTags?: string | string[]; // 인라인태그 지정
  preWhitespaceDetectedTags?: string | string[]; // 줄바꿈 자동 감지 태그

  // 번역문 스타일
  translationClasses?: string | string[]; // 번역문에 추가할 클래스

  // 전역 스타일
  globalStyles?: Record<string, string>; // 페이지 스타일 수정
  globalAttributes?: Record<string, Record<string, string | null>>; // 요소 속성값 수정

  // CSS 임베드
  injectedCss?: string | string[]; // CSS 임베드
  additionalInjectedCss?: string | string[]; // 추가 CSS

  // 컨텍스트
  wrapperPrefix?: string; // 번역 부분 앞에 붙는 텍스트/HTML
  wrapperSuffix?: string; // 번역 부분 뒤에 붙는 텍스트/HTML

  // 번역문 줄바꿈 기준
  blockMinTextCount?: number; // 블록 단위 최소 글자수
  blockMinWordCount?: number; // 블록 단위 최소 단어수

  // 번역 대상 최소 글자수
  containerMinTextCount?: number; // 요소 최소 글자수
  paragraphMinTextCount?: number; // 단락 최소 글자수
  paragraphMinWordCount?: number; // 단락 최소 단어수

  // 장문 강제 줄바꿈 글자수
  lineBreakMaxTextCount?: number; // 단락 최대 글자수

  // 번역 시작 시점
  urlChangeDelay?: number; // 페이지 진입 후 번역 지연 (ms)
  observeUrlChange?: boolean; // URL 변경 시 재번역

  // 모바일
  isShowUserscriptPagePopup?: boolean; // 모바일에서 번역 팝업 표시
  fingerCountToToggleTranslagePageWhenTouching?: number; // 지원 중단됨

  // AI 스트리밍 번역
  aiRule?: {
    streamingSelector: string; // 번역 중인 요소 셀렉터
    messageWrapperSelector: string; // 메시지 내용 셀렉터
    streamingChange: boolean; // 점진 갱신 여부
  };
}

사용 전 안내​

진입점과 우선순위​

빠른 시작 (가장 흔한 요구)​

1) 특정 사이트의 본문만 번역하기​

2) 항상 번역 / 아예 번역 안 함​

3) 사이트별로 번역 엔진 다르게 사용하기​

4) 사이트별 번역 결과 스타일 지정​

5) 번역으로 인해 스타일이 이상해졌을 때 스타일 수정​

6) 미설정된 번역 서비스를 메뉴에 표시하지 않음​

규칙과 매칭​

규칙 병합​

matches 의 일반적인 형태​

selectors / excludeSelectors​

상속과 증분 수정 (.add / .remove)​

주요 필드 (발췌)​

GPT 류 스트리밍 채팅 번역​

matches 매칭 로직 (간단 설명)​

사이트 적용 예시 (Twitter)​

사용자 정의 사이트 적용​

번역 서비스 설정​

요청 타임아웃 설정 (최대 대기시간)​

언어 및 번역 전략​

항상 번역 / 번역 금지 언어 설정​

특정 사이트에 소스 언어 지정​

기타 자주 쓰이는 글로벌 설정​

번역문에서 HTML 태그 렌더링 허용​

번역 스타일 및 테마​

AI / 고급 서비스 파라미터​

무료 AI 번역 모드​

temperature​

사용자 정의 요청 헤더·바디​

Gemini 계열 모델 사용자 정의 설정​

사용자 정의 프롬프트 완전 준수​

다국어 프롬프트 커스텀 (부분 예시)​

용어집 & 기계 번역​

캐시 자동 정리 주기​

Injected CSS 와 globalStyles 의 차이​

디버깅 및 흔한 실수​

부록: Rule 필드 참고​