← 전체 코드 목록

📖 사용 방법

구글 시트에 한국어 단어를 입력하면, AI가 자동으로 중국어와 병음을 찾아 채워주는 편리한 기능을 만들어 보세요.

이런 분께 추천해요

  • 중국어 단어를 학습하거나 정리하는 분
  • 한국어 단어를 중국어로 빠르게 변환하고 싶은 분
  • AI를 활용해 반복 작업을 자동화하고 싶은 분

완성하면 이렇게 됩니다

구글 시트의 A열에 한국어 단어를 입력하면, B열에는 중국어 단어가, C열에는 병음(성조 포함)이 자동으로 채워집니다. 여러 단어를 한 번에 복사하여 붙여넣어도 AI가 순서대로 처리해 드립니다. 처리 중에는 '생성중...' 메시지가 표시되어 진행 상황을 알 수 있습니다.

준비물

  • Google 계정: 구글 시트(Google Sheets)와 앱스 스크립트(Apps Script, 구글 서비스 자동화를 위한 프로그래밍 환경) 사용을 위해 필요합니다.
  • Gemini API 키: AI 기능을 사용하기 위해 필요합니다.

따라하기

1단계: 새 구글 시트 준비 및 코드 복사

  1. 새 구글 시트 만들기: 웹 브라우저에서 drive.google.com에 접속하신 후, 왼쪽 상단의 + 새로 만들기 버튼을 클릭하고 Google 스프레드시트를 선택하여 새 시트를 만듭니다.
  2. 시트 이름 변경: 새로 만들어진 시트의 이름을 시트1로 변경합니다. (코드에서 SHEET_NAME = "시트1"로 설정되어 있습니다.)
  3. 앱스 스크립트 열기: 시트 상단 메뉴에서 확장 프로그램Apps Script를 클릭하여 앱스 스크립트 편집기를 엽니다.
  4. 기존 코드 삭제: 앱스 스크립트 편집기에서 코드.gs 파일에 있는 내용을 모두 지웁니다.
  5. 코드 붙여넣기: 아래 [코드]를 복사하여 코드.gs 파일에 붙여넣습니다.
  6. 저장: 편집기 상단의 디스크 모양 저장 아이콘을 클릭하여 코드를 저장합니다.

2단계: Gemini API 키 설정

  1. API 키 발급: 웹 브라우저에서 aistudio.google.com에 접속하신 후, Get API key in Google AI Studio (또는 API 키 가져오기) 버튼을 클릭합니다.
  2. 새 API 키 생성: Create API Key (또는 API 키 만들기) 버튼을 클릭하여 새로운 API 키를 발급받습니다. 발급된 키를 복사해 둡니다.
  3. 코드에 붙여넣기: 앱스 스크립트 편집기로 돌아와서, 코드의 const GEMINI_API_KEY = "YOUR_API_KEY"; 부분에서 "YOUR_API_KEY" 대신 복사한 API 키를 붙여넣습니다. (따옴표는 그대로 유지해야 합니다.)
  4. 저장: 다시 한번 저장 아이콘을 클릭하여 코드를 저장합니다.

3단계: 트리거 설치 및 권한 부여

  1. 트리거 설치 함수 실행: 앱스 스크립트 편집기 상단의 함수 선택 드롭다운 메뉴에서 installOnEditTrigger를 선택하고, 옆의 실행 (▶) 버튼을 클릭합니다. 이 함수는 시트가 수정될 때마다 번역 기능이 자동으로 작동하도록 하는 트리거(자동 실행 장치)를 설치합니다.
  2. 권한 검토: 처음 실행 시 권한 검토 팝업이 뜨면 클릭합니다.
  3. Google 계정 선택: 본인의 Google 계정을 선택합니다.
  4. 경고 화면 처리: 이 앱은 Google에서 확인되지 않았습니다라는 경고 화면이 나오면, 왼쪽 하단의 고급을 클릭한 후 (프로젝트 이름)으로 이동을 클릭합니다.
  5. 권한 허용: 마지막으로 허용 버튼을 클릭하여 앱스 스크립트가 구글 시트에 접근하고 외부 AI 서비스(Gemini)를 사용할 수 있도록 권한을 부여합니다.
  6. 실행 완료 확인: 앱스 스크립트 편집기 하단의 실행 로그에서 실행 완료 메시지가 나타나는지 확인합니다.

4단계: 시트에서 사용하기

  1. 구글 시트로 돌아가기: 앱스 스크립트 편집기를 닫고 구글 시트로 돌아갑니다.
  2. A열에 한국어 단어 입력: 예를 들어, A2 셀에 "사과"라고 입력한 후 Enter 키를 누릅니다.
  3. 자동 변환 확인: 잠시 후 B2 셀에 중국어 단어가, C2 셀에 병음이 자동으로 나타나는 것을 확인하실 수 있습니다.
  4. 여러 단어 입력: 여러 한국어 단어를 A열에 복사하여 붙여넣어도 자동으로 변환됩니다.

자주 막히는 부분

  • API 키 오류: 코드의 GEMINI_API_KEY 변수에 발급받은 API 키가 정확하게 입력되었는지, 따옴표 안에 잘 들어갔는지 다시 한번 확인해 주세요. API 키 발급 과정에서 문제가 없었는지도 확인해 보시는 것이 좋습니다.
  • 트리거 설치 오류: installOnEditTrigger 함수를 실행했는지, 그리고 권한 허용 절차를 제대로 완료했는지 확인해 주세요. 권한을 허용하지 않으면 스크립트가 작동할 수 없습니다.
  • 시트 이름 오류: 구글 시트의 이름이 시트1이 맞는지 확인해 주세요. 만약 다른 이름으로 사용하고 싶다면, 코드의 const SHEET_NAME = "시트1"; 부분을 원하는 시트 이름으로 변경해야 합니다.
  • 열 위치 오류: 한국어 단어를 A열에 입력했는지 확인해 주세요. 코드에서 COL.WORD가 1(A열)로 설정되어 있습니다.
  • '생성중...'만 계속 표시: API 호출에 문제가 있거나, Gemini API의 사용량 제한에 걸렸을 수 있습니다. 잠시 기다리거나, 앱스 스크립트 편집기의 실행 로그를 확인하여 더 자세한 오류 메시지를 확인해 보세요.

이렇게도 써보세요 (응용)

  • 다른 언어 번역: translateToChineseAndPinyin 함수와 prompt(AI에게 내리는 지시문) 내용을 수정하여 한국어-일본어, 한국어-영어 등 다른 언어로 번역하도록 만들 수 있습니다.
  • 다른 정보 추가: 프롬프트에 요청할 내용을 추가하여 단어의 뜻, 예문 등 더 많은 정보를 받아올 수 있습니다. 단, Gemini API의 응답 형식과 시트의 열 구성을 맞춰야 합니다.
  • 번역 모델 변경: 코드의 MODEL 변수를 gemini-1.5-pro 등 다른 Gemini 모델로 변경하여 사용할 수 있습니다. (모델별 성능과 비용을 고려해 선택하세요.)
  • 시트 설정 변경: 코드의 SHEET_NAME이나 COL 설정을 변경하여 원하는 시트 이름과 열에 맞게 기능을 사용할 수 있습니다.

한 줄 정리

구글 시트와 AI를 활용해 한국어-중국어 단어 번역을 자동화하고, 학습 효율을 높여 보세요!

💻 코드

Code.gs
/***** 설정 *****/
const GEMINI_API_KEY = "YOUR_API_KEY";   // gemini-2.5-flash 키
const MODEL = "gemini-2.5-flash";

const SHEET_NAME = "시트1";
const COL = { WORD:1, ZH:2, PINYIN:3 };  // A:단어, B:중국어, C:병음


/***** 설치형 onEdit 트리거에서 호출되는 함수 (이름 중요: onEdit 아님!) *****/
function handleEdit(e) {
  const range = e.range;
  const sheet = range.getSheet();
  if (sheet.getName() !== SHEET_NAME) return;

  const col = range.getColumn();
  const row = range.getRow();

  // A열만 처리, 1행은 제외
  if (col !== COL.WORD || row === 1) return;

  const values = range.getValues(); // 복붙 대비
  const numRows = values.length;

  for (let i = 0; i < numRows; i++) {
    const word = values[i][0];
    const targetRow = row + i;

    if (!word) {
      sheet.getRange(targetRow, COL.ZH).setValue("");
      sheet.getRange(targetRow, COL.PINYIN).setValue("");
      continue;
    }

    // ★ 먼저 '생성중...' 표시
    sheet.getRange(targetRow, COL.ZH).setValue("생성중...");
    sheet.getRange(targetRow, COL.PINYIN).setValue("...");

    Utilities.sleep(80); // 복붙 시 과도한 호출 방지용(선택)

    try {
      const result = translateToChineseAndPinyin(word);
      if (!result) continue;

      sheet.getRange(targetRow, COL.ZH).setValue(result.zh);
      sheet.getRange(targetRow, COL.PINYIN).setValue(result.pinyin);

    } catch (err) {
      // ★ 에러가 나도 셀에는 계속 '생성중...'만 유지
      Logger.log("변환 오류: " + err);
      sheet.getRange(targetRow, COL.ZH).setValue("생성중...");
      sheet.getRange(targetRow, COL.PINYIN).setValue("...");
    }
  }
}


/***** Gemini API 호출 함수 *****/
function translateToChineseAndPinyin(koreanWord) {
  const url =
    `https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent?key=${GEMINI_API_KEY}`;

  const prompt = `
다음 한국어 단어를 중국어와 병음으로 변환해줘.

규칙:
1. 출력 형식은 "중국어|병음" 한 줄만 작성.
2. 병음은 성조 포함(ā á ǎ à).
3. 예: "책" → "书|shū"
4. 다른 문장, 설명, 예문 금지.

한국어 단어: "${koreanWord}"
  `.trim();

  const payload = {
    contents: [
      {
        parts: [{ text: prompt }]
      }
    ]
  };

  const options = {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify(payload),
    muteHttpExceptions: true
  };

  const response = UrlFetchApp.fetch(url, options);
  const code = response.getResponseCode();

  if (code !== 200) {
    throw new Error("API Error: " + code + " - " + response.getContentText());
  }

  const data = JSON.parse(response.getContentText());
  const text =
    data.candidates?.[0]?.content?.parts?.[0]?.text?.trim() || "";

  if (!text) throw new Error("응답 없음");

  const parts = text.split("|").map(s => s.trim());
  if (parts.length < 2) throw new Error("형식 오류: " + text);

  return {
    zh: parts[0],
    pinyin: parts[1]
  };
}


/***** 설치형 onEdit 트리거 생성 함수 *****/
function installOnEditTrigger() {
  // 기존 트리거 정리
  ScriptApp.getProjectTriggers().forEach(t => {
    if (t.getHandlerFunction() === "handleEdit") {
      ScriptApp.deleteTrigger(t);
    }
  });

  ScriptApp.newTrigger("handleEdit")
    .forSpreadsheet(SpreadsheetApp.getActive())
    .onEdit()
    .create();
}

🤖 사용한 AI 프롬프트

구글 시트와 구글 앱스 스크립트를 사용해서 한국어를 중국어와 병음으로 변환하는 작업을 할 거야. A열에 한국어를 쓰고, B열에 중국어가 자동으로 번역되고, C열에 병음이 자동으로 생성되도록 해줘. 그래서 헤더는 한국어, 중국어, 병음이야. 시트 이름은 시트1로 되어 있어. 
트리거는 직접 단어를 입력하거나, 복사 붙여넣기 하는 것도 트리거가 되도록 해줘. 
API 키는 gemini 2.5 flash 버전을 사용할 거야. 
바로 복사해서 쓸 수 있도록 하나의 GS 파일로 만들어줘. 
handleEdit, translateToChineseAndPinyin, installOnEditTrigger 함수를 사용해서 만들어 줘. 

🎬 관련 영상