snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/export-faq.mdx

@@ -0,0 +1,32 @@
+---
+title: 내보내기 FAQ
+description: 데이터 내보내기에 대한 자주 묻는 질문입니다.
+---
+
+<AccordionGroup>
+<Accordion title="취소 전에 워크스페이스의 모든 데이터를 내보낼 수 있나요? 사용자 정의 오브젝트, 사용자 정의 필드, 관계, 메모, 작업, 기회, 첨부 파일, 워크플로, 권한, 감사 내역을 모두 포함해서요.">
+워크스페이스 데이터는 일부 예외를 제외하고 취소 전에 내보낼 수 있습니다. 대시보드, 워크플로, 권한은 수동으로 이전해야 하며, 감사 로그는 이전할 수 없습니다.
+</Accordion>
+<Accordion title="현재 내보내거나 마이그레이션할 수 없는 요소는 무엇인가요?">
+대부분의 요소는 일부 예외를 제외하고 내보내거나 마이그레이션할 수 있습니다:
+* 워크플로, 대시보드 및 모든 설정(API 키, 웹훅, 감사 로그, 사용자 설정 등) 수동으로 마이그레이션해야 합니다.
+* 앱에서 생성한 오브젝트와 필드는 해당 앱을 다른 워크스페이스에 설치하여 마이그레이션할 수 있습니다. 수동으로 마이그레이션해서는 안 됩니다.
+* 워크플로 버전 및 워크플로 실행과 같은 일부 레코드는 전혀 이전할 수 없으며 손실될 것으로 예상됩니다.
+* 메시지 및 캘린더 관련 오브젝트와 같은 일부 오브젝트는 계정이 연결될 때 생성되고 주기적으로 동기화되므로 내보내지 말아야 합니다. 계정을 연결하면 다시 동기화됩니다(계정에 계속 액세스할 수 있는 경우에 한하며, 퇴사한 팀 구성원의 계정인 경우 해당 메시지는 반드시 내보내야 하며, 그렇지 않으면 손실됩니다).
+</Accordion>
+<Accordion title="클라우드에서 셀프 호스팅으로 마이그레이션하기 위한 공식 절차나 마이그레이션 지원 서비스가 있나요?">
+현재로서는 클라우드에서 셀프 호스팅으로 마이그레이션하기 위한 공식 절차는 없습니다. 일반적인 절차는 다음과 같습니다:
+* 먼저 앱을 설치하여 앱 소유 오브젝트와 필드를 추가합니다.
+* 사용자가 추가한 사용자 정의 오브젝트와 필드를 복제합니다.
+* API 키나 AI 도구를 사용하는 스크립트를 활용하여 한 워크스페이스의 모든 데이터를 다른 워크스페이스로 마이그레이션합니다.
+* 모든 이전 불가능한 오브젝트는 수동으로 마이그레이션해야 합니다.
+
+다음 사항을 유의해 주세요:
+* 요청/분 제한에 도달하기 전까지 Pro 플랜에서는 분당 최대 50개, Organization 플랜에서는 분당 최대 100개의 요청을 보낼 수 있습니다.
+* 각 API 요청에는 최대 200개의 레코드를 포함할 수 있습니다.
+* Created by, Timeline activities, Updated by와 같은 필드의 일부 데이터는 가져오기 중에 손실되며 시스템에 의해 덮어써집니다.
+</Accordion>
+<Accordion title="내보낸 파일은 개방형이며 문서화된 형식으로 제공되나요?">
+UI에서 내보낸 파일은 Excel 형식이며, 모든 API 요청은 JSON 형식으로 저장할 수 있습니다.
+</Accordion>
+</AccordionGroup>

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/export-your-data.mdx

@@ -0,0 +1,209 @@
+---
+title: 데이터 내보내기
+description: Twenty에서 데이터를 내보내는 포괄적인 단계별 가이드.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## 개요
+
+백업, 보고, 또는 마이그레이션을 위해 워크스페이스 데이터를 CSV로 내보내세요.
+
+**사용 사례:**
+
+* **정기 백업** — 데이터 사본을 보관하세요
+* **외부 보고** — Excel, Google Sheets 또는 BI 도구에서 데이터를 분석하세요
+* **마이그레이션** — 데이터를 다른 시스템으로 이동하세요
+* **대량 업데이트** — 내보내고, 편집한 후, 다시 가져와 레코드를 업데이트하세요
+
+## 알아두어야 할 사항
+
+### 내보내기 제한
+
+* 내보내기 1회당 **최대 20,000개 레코드**
+* **표시된 열**만 내보내집니다
+* **필터링된 레코드**만 내보내집니다(현재 보기 기준)
+
+<Note>더 큰 내보내기(20,000개 이상의 레코드)에는 필터를 사용해 배치로 내보내거나 [API](/l/ko/developers/extend/api)를 사용하세요.</Note>
+
+### 권한
+
+데이터를 내보내려면 **"Export CSV"** 권한이 필요합니다. 이 옵션이 없다면 워크스페이스 관리자에게 문의하세요.
+
+## 1단계: 객체로 이동
+
+내보내려는 객체로 이동하세요:
+
+* **People** — 연락처
+* **Companies** — 조직
+* **Opportunities** — 거래
+* **사용자 지정 객체** — 사용자가 생성한 모든 객체
+
+## 2단계: 보기 구성
+
+**중요:** 내보내기에는 현재 보기에서 보이는 내용만 포함됩니다.
+
+### 열 추가/제거
+
+1. **옵션 → 필드**를 클릭합니다(또는 열 끝의 **+**).
+2. 내보내려는 필드를 선택하세요
+3. 불필요한 필드의 선택을 해제하세요
+
+### 레코드 필터링(선택 사항)
+
+일부 데이터만 필요하다면:
+
+1. **필터**를 클릭합니다
+2. 필터 조건을 추가하세요(예: "Created date > January 1, 2024")
+3. 조건과 일치하는 레코드만 내보내집니다
+
+### 레코드 정렬(선택 사항)
+
+1. 정렬하려면 열 헤더를 클릭하세요
+2. 내보내기는 정렬 순서를 따릅니다
+
+<Note>**내보내기 전용 보기를 만드세요.** 내보내기에 맞게 구성한 보기를 저장해 매번 다시 구성할 필요가 없도록 하세요.</Note>
+
+## 3단계: 데이터 내보내기
+
+1. 테이블 오른쪽 상단의 **⋮** 아이콘을 클릭하세요
+2. **Export view**를 선택하세요
+3. CSV 파일을 저장할 위치를 선택하세요
+4. 다운로드가 완료될 때까지 기다리세요
+
+## 내보내지는 내용
+
+| 포함됨             | 포함되지 않음     |
+| --------------- | ----------- |
+| 모든 표시된 열        | 숨김 열        |
+| 현재 필터와 일치하는 레코드 | 필터로 제외된 레코드 |
+| 사용자 지정 필드 값     | 보기에 없는 필드   |
+| 레코드 ID          | 파일 첨부       |
+| 관계 ID           | 이미지         |
+
+### 관계 필드
+
+관계 ID는 관계의 **"many" 측**에서만 내보내집니다:
+
+* **People 내보내기**에는 `companyId` 열이 포함됩니다(People → Company 관계)
+* **Companies 내보내기**에는 `peopleIds`가 포함되지 않습니다(Companies는 "one" 측입니다)
+
+즉, People 내보내기를 사용해 다시 가져오면서 Company 연결을 유지할 수 있지만, 관계를 다시 만들려면 Companies 이후에 People을 다시 가져와야 합니다.
+
+## 용도별 내보내기
+
+### 백업용
+
+1. **모든 필드**가 보이도록 보기를 만들세요
+2. 모든 레코드를 포함하려면 모든 필터를 제거하세요
+3. 각 객체 유형을 별도로 내보내세요
+4. 내보낸 파일을 안전한 위치에 보관하세요
+5. 반복 알림을 설정하세요(매주/매월)
+
+### 외부 보고용
+
+1. 분석에 필요한 필드만 포함하세요
+2. 관련 데이터에 집중할 수 있도록 필터를 적용하세요
+3. 분석할 필드로 정렬하는 것을 고려하세요
+
+### 대량 업데이트용
+
+1. 업데이트하려는 레코드를 내보내세요
+2. 고유 식별자(`email`, `domain` 또는 `id`)를 포함하세요
+3. 내보낸 파일을 편집하세요
+4. 다시 가져와 레코드를 업데이트하세요
+   참고: [기존 레코드를 업데이트하는 방법](/l/ko/user-guide/data-migration/how-tos/update-existing-records-via-import)
+
+### 마이그레이션용
+
+다른 시스템으로 마이그레이션하기 위해 내보내는 경우:
+
+1. **각 객체를 개별적으로 내보내세요** — People, Companies, Opportunities 등
+2. **ID 필드를 포함하세요** — 관계를 유지하는 데 도움이 됩니다
+3. **필드 매핑을 문서화하세요** — Twenty의 필드가 대상 시스템에 어떻게 매핑되는지 기록하세요
+
+## 대용량 데이터셋 처리(20,000개 이상 레코드)
+
+내보내기 한도는 20,000개 레코드입니다. 더 큰 데이터셋의 경우:
+
+### 옵션 1: 배치로 내보내기
+
+1. 필터를 추가하세요(예: "Created date" 범위)
+2. 첫 번째 배치를 내보내세요
+3. 필터를 변경하세요
+4. 다음 배치를 내보내세요
+5. 스프레드시트에서 파일을 결합하세요
+
+**배치용 예시 필터:**
+
+* 날짜 범위별(1월, 2월, 3월...)
+* 소유자별(팀원 A, 팀원 B...)
+* 상태별(활성, 비활성...)
+
+### 옵션 2: API 사용
+
+API에는 레코드 수 한도가 없습니다:
+
+1. API 키를 **설정 → 개발자**에서 발급받으세요
+2. GraphQL API를 사용해 레코드를 쿼리하세요
+3. 애플리케이션에서 결과를 처리하세요
+
+참고: [API 문서](/l/ko/developers/extend/api)
+
+## 팁 및 모범 사례
+
+### 내보내기용 보기 만들기
+
+내보내기에 맞게 구성한 보기를 저장하세요:
+
+1. 열과 필터를 구성하세요
+2. **보기 옵션** → **새 보기로 저장**을 클릭하세요
+3. "Export - [Purpose]"로 이름을 지정하세요
+
+### 내보낸 파일 보호
+
+내보낸 파일에는 민감한 데이터가 포함될 수 있습니다:
+
+* 안전한 위치에 보관하세요
+* 더 이상 필요하지 않은 내보낸 파일은 삭제하세요
+* 내보낸 파일을 공유할 때 주의하세요
+
+### 내보내기 전 확인 사항
+
+<Check>올바른 열이 표시되어 있습니다</Check>
+<Check>필터가 올바르게 설정되어 있습니다(전체 내보내기의 경우 제거)</Check>
+<Check>내보내기 권한이 있습니다</Check>
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="내보낸 파일에 일부 열이 없는 이유는 무엇인가요?">
+    표시된 열만 내보내집니다. 내보내기 전에 **옵션 → 필드**에서 필요한 열을 추가하세요.
+  </Accordion>
+
+  <Accordion title="내보낸 파일에 모든 레코드가 포함되지 않은 이유는 무엇인가요?">
+    필터를 확인하세요. 내보내기에는 현재 보기의 필터와 일치하는 레코드만 포함됩니다. 모든 레코드를 내보내려면 필터를 제거하세요.
+  </Accordion>
+
+  <Accordion title="20,000개 이상의 레코드를 내보낼 수 있나요?">
+    단일 내보내기로는 불가능합니다. 필터를 사용해 배치로 내보내거나, 더 큰 데이터셋에는 API를 사용하세요.
+  </Accordion>
+
+  <Accordion title="내보낸 파일의 형식은 무엇인가요?">
+    CSV(쉼표로 구분된 값). Excel, Google Sheets 또는 어떤 스프레드시트 애플리케이션에서도 열 수 있습니다.
+  </Accordion>
+
+  <Accordion title="관계 ID가 포함되나요?">
+    예. 다만 관계의 "many" 측에서만 포함됩니다. 예를 들어 People 내보내기에는 `companyId`가 포함되지만, Companies 내보내기에는 people ID가 포함되지 않습니다.
+  </Accordion>
+
+  <Accordion title="내보내기를 자동화할 수 있나요?">
+    UI만으로는 불가능합니다. API를 사용해 자동화된 내보내기 워크플로우를 구축하세요.
+  </Accordion>
+</AccordionGroup>
+
+## 다음 단계
+
+* [기존 레코드를 업데이트하는 방법](/l/ko/user-guide/data-migration/how-tos/update-existing-records-via-import) — 내보낸 파일을 편집한 뒤 다시 가져오세요
+* [API로 데이터 가져오는 방법](/l/ko/user-guide/data-migration/how-tos/import-data-via-api) — 대용량 데이터셋용
+* [API 문서](/l/ko/developers/extend/api) — 맞춤 내보내기 워크플로우를 구축하세요

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/fix-import-errors.mdx

@@ -0,0 +1,430 @@
+---
+title: 가져오기 오류 해결
+description: CSV 가져오기 오류를 해결하기 위한 종합적인 문제 해결 가이드.
+---
+
+## 개요
+
+가져오기가 안 되나요? 이 가이드는 일반적인 가져오기 오류를 단계별로 식별하고 해결하도록 도와줍니다.
+
+## 가져오기 유효성 검사가 작동하는 방식
+
+파일을 업로드하고 열을 매핑한 후, Twenty가 데이터에 대해 유효성 검사를 수행합니다:
+
+1. **유효성 검사를 실행** — Twenty가 각 행에서 오류를 확인합니다
+2. **오류가 강조 표시됨** — 문제가 있는 행은 **노란색**으로 표시됩니다
+3. **바로 수정 가능** — 가져오기 UI에서 셀을 직접 편집합니다
+4. **또는 행을 제거** — 문제가 있는 레코드를 완전히 건너뜁니다
+
+<Note>**UI에서 오류를 수정하세요.** 스프레드시트로 돌아갈 필요가 없습니다. 가져오는 동안 셀을 직접 편집하여 시간을 절약하세요.</Note>
+
+## 단계별 문제 해결
+
+### 1단계: 오류 유형 식별
+
+강조 표시된 행을 클릭하여 특정 오류 메시지를 확인하세요. 일반적인 오류 유형:
+
+| 오류 메시지                                                           | 의미                                |
+| ---------------------------------------------------------------- | --------------------------------- |
+| 중복 값이 노란색으로 강조 표시됨                                               | 값이 Twenty에 이미 존재하거나 파일에 두 번 나타납니다 |
+| `{field} is not a valid {type}` (노란색 셀에 커서를 올리세요)                | 데이터가 예상 형식과 일치하지 않음               |
+| 필수 필드가 강조 표시됨                                                    | 필수 필드가 비어 있음                      |
+| `Can't connect to {object}. No unique record found...` (가져오기 실패) | 참조된 레코드가 존재하지 않음                  |
+| `Too many records. Up to 10000 allowed` (업로드 차단됨)                | 파일의 레코드가 10,000개를 초과함             |
+
+### 2단계: 오류 수정
+
+오류 유형별로 아래의 구체적인 지침을 따르세요.
+
+---
+
+## 오류: 중복 값
+
+### 볼 수 있는 내용
+
+가져오기를 시작하기 전에 가져오기 UI에서 중복 값이 있는 행이 **노란색으로 강조 표시**됩니다.
+
+### 의미
+
+고유 필드(이메일, 도메인)가 다음에 해당함:
+
+* Twenty에 이미 존재함
+* 파일에 두 번 나타남
+
+### 해결 방법
+
+**옵션 1: 중복 값을 편집**
+
+1. 오류가 있는 셀을 클릭
+2. 고유 값으로 변경
+3. 가져오기를 계속
+
+**옵션 2: 중복 행 제거**
+
+1. 행 옆의 X를 클릭
+2. 해당 행은 가져오기 중에 건너뜁니다
+
+**옵션 3: Twenty로 기존 레코드를 업데이트**
+
+1. 파일에 고유 식별자(`email`, `domain`, 또는 `id`)가 포함되어 있는지 확인하세요
+2. 고유 식별자 필드를 매핑하세요
+3. Twenty가 중복을 생성하는 대신 기존 레코드를 업데이트합니다
+
+<Note>
+**고유 필드도 업데이트할 수 있습니다.**
+
+* `id`는 유지하고 `email`만 변경하면 → 이메일이 업데이트됩니다
+* `email`은 유지하고 `id`만 변경하면 → id가 업데이트됩니다
+
+하나의 고유 식별자만 일치해도 Twenty가 레코드를 업데이트합니다.
+</Note>
+
+### 이 오류를 방지하는 방법
+
+가져오기 전:
+
+1. 스프레드시트를 고유 필드로 정렬
+2. 중복 행 제거
+3. 레코드가 Twenty에 이미 존재하는지 확인
+
+<Warning>
+**소프트 삭제된 레코드도 고유성에 포함됩니다.**
+
+Command 메뉴 → 삭제된 레코드 보기를 확인하세요. 그곳의 레코드도 여전히 고유성을 강제합니다. 완전히 삭제하거나 복원한 뒤 업데이트하세요.
+</Warning>
+
+자세한 내용: [고유성 제약 조건](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)
+
+---
+
+## 오류: 잘못된 형식
+
+### 볼 수 있는 내용
+
+셀 값이 노란색으로 강조 표시됩니다. 해당 부분에 커서를 올리면 오류 메시지가 표시됩니다:
+
+```
+{field name} is not a valid {field type}
+```
+
+### 의미
+
+데이터가 해당 필드 유형의 예상 형식과 일치하지 않습니다.
+
+### 해결 방법 — 필드 유형별
+
+#### 이메일
+
+**문제:** 잘못된 이메일 형식
+**해결:** `name@domain.com` 형식을 사용하세요
+
+```
+❌ john.smith@
+❌ john smith@acme.com
+✓ john.smith@acme.com
+```
+
+#### 도메인
+
+**문제:** 일관되지 않은 형식은 중복을 유발할 수 있음
+**해결:** `https://domain.com` 형식을 사용하세요(권장)
+
+```
+⚠️ acme.com         (valid, but not recommended)
+⚠️ www.acme.com     (valid, but not recommended)
+✅ https://acme.com  (recommended)
+```
+
+<Note>모든 형식이 유효하지만 `https://domain.com`은 이메일/캘린더 동기화에서 사용하는 형식과 일치하므로 권장됩니다. 다른 형식을 사용하면 회사가 중복으로 생성될 수 있습니다.</Note>
+
+#### 날짜
+
+**문제:** 인식되지 않는 날짜 형식
+**해결:** 파일 전체에서 `YYYY-MM-DD` 형식을 일관되게 사용하세요
+
+```
+✓ 2024-03-15        (YYYY-MM-DD)
+❌ 03/15/2024        (MM/DD/YYYY)
+❌ 15/03/2024        (DD/MM/YYYY)
+```
+
+#### 전화
+
+**문제:** 필수 열 누락
+**해결:** 모든 전화 열을 포함하세요
+
+| 열                                       | 예시           |
+| --------------------------------------- | ------------ |
+| **Phones / Primary Phone Number**       | `4159095555` |
+| **Phones / Primary Phone Country Code** | `US`         |
+| **Phones / Primary Phone Calling Code** | `+1`         |
+
+#### 부울
+
+**문제:** 잘못된 불리언 값
+**해결:** 대문자 `TRUE` 또는 `FALSE`를 사용하세요
+
+```
+❌ true
+❌ yes
+❌ 1
+✓ TRUE
+✓ FALSE
+```
+
+#### 선택 / 다중 선택
+
+**문제:** 값이 기존 옵션과 일치하지 않음
+**해결:** 표시 라벨이 아니라 **API 이름**을 사용하세요
+
+API 이름을 찾는 방법:
+
+1. **설정 → 데이터 모델**로 이동
+2. 객체와 필드를 선택하세요
+3. **고급 모드**를 활성화하세요(오른쪽 하단 토글)
+4. API 이름을 사용하세요(예: `OPTION_1`, "Option 1" 아님)
+
+```
+❌ High Priority
+✓ HIGH_PRIORITY
+```
+
+#### 통화
+
+**문제:** 금액 또는 통화 코드 누락
+**해결:** 두 열 모두 채우세요
+
+| 열                     | 예시        |
+| --------------------- | --------- |
+| **Amount / Amount**   | `1234.56` |
+| **Amount / Currency** | `USD`     |
+
+#### 숫자
+
+**문제:** 숫자가 아닌 문자 포함
+**해결:** 숫자만 사용하고 소수점은 점(.)을 사용하세요
+
+```
+❌ $1,234.56
+❌ 1,234.56
+✓ 1234.56
+```
+
+전체 형식 참고: [필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping)
+
+---
+
+## 오류: 필수 필드 누락
+
+### 볼 수 있는 내용
+
+해당 행이 노란색으로 강조 표시되고 필수 필드 셀이 표시됩니다.
+
+### 의미
+
+이 행의 필수 필드가 비어 있습니다.
+
+### 해결 방법
+
+**옵션 1: 값 입력**
+
+1. 빈 셀을 클릭
+2. 값 입력
+3. 가져오기를 계속
+
+**옵션 2: 행 제거**
+
+1. 데이터가 없다면 X를 클릭해 해당 행을 건너뛰세요
+
+### 이 오류를 방지하는 방법
+
+가져오기 전에 필수 필드를 확인하세요:
+
+1. **설정 → 데이터 모델**로 이동
+2. 객체를 선택하세요
+3. 어떤 필드가 필수로 표시되어 있는지 확인하세요
+
+---
+
+## 오류: 관계를 찾을 수 없음
+
+### 볼 수 있는 내용
+
+이 오류는 **가져오기가 시작된 후** 나타나며, 다음과 같은 메시지와 함께 가져오기가 실패합니다:
+
+```
+Can't connect to company. No unique record found with condition: id = 7776ee49-f608-4a77-8cc8-6fe96ae1e43f
+```
+
+이는 해당 식별자를 가진 Company가 Twenty에 없다는 의미입니다.
+
+<Note>다른 오류와 달리, 이 오류는 데이터 검토 단계에서 감지되지 않습니다. 가져오기가 시작된 뒤 누락된 관계를 만나면 실패합니다.</Note>
+
+### 의미
+
+Twenty에 존재하지 않는 레코드에 연결하려고 하고 있습니다.
+
+### 해결 방법
+
+**옵션 1: 상위 레코드를 먼저 가져오기**
+
+1. 현재 가져오기를 취소
+2. 상위 레코드(예: Companies)를 가져오기
+3. 그런 다음 하위 레코드(예: People)를 가져오기
+
+**옵션 2: 참조 값 수정**
+
+1. 파일의 참조 값을 확인
+2. 기존 레코드와 정확히 일치하는지 확인
+3. 형식 확인: 도메인은 `https://domain.com`이어야 합니다
+
+**옵션 3: 관계 제거**
+
+1. 관계 없이 가져오려면 셀을 비우세요
+2. 관계를 나중에 수동으로 추가하세요
+
+### 이 오류를 방지하는 방법
+
+1. **올바른 순서로 가져오기:**
+   * 회사 먼저
+   * 연락처 두 번째(회사 참조 포함)
+   * 기회 세 번째
+
+2. **참조 값을 확인하세요:**
+   * 정확한 식별자를 얻기 위해 상위 레코드를 내보내세요
+   * 도메인은 `https://domain.com` 형식을 사용하세요
+   * 오타 및 대소문자 구분 여부를 확인하세요
+
+<Warning>
+**존재하지 않는 레코드를 참조하면 가져오기는 실패합니다.**
+
+항상 상위 객체를 먼저 가져오세요.
+</Warning>
+
+자세한 내용: [관계 가져오기](/l/ko/user-guide/data-migration/capabilities/import-relations)
+
+---
+
+## 오류: 파일이 너무 큼
+
+### 볼 수 있는 내용
+
+이 오류는 **파일을 업로드할 때** 나타나며 — 업로드가 완전히 차단됩니다:
+
+```
+Too many records. Up to 10000 allowed
+```
+
+파일 크기를 줄이기 전에는 데이터 검토 단계로 진행할 수 없습니다.
+
+### 의미
+
+파일의 레코드가 10,000개를 초과합니다.
+
+### 해결 방법
+
+**옵션 1: 여러 파일로 분할**
+
+1. 데이터를 10,000개 이하의 레코드로 구성된 파일로 나누세요
+2. 각 파일을 개별적으로 가져오세요
+3. 가져오기 순서를 유지(회사를 연락처보다 먼저)
+
+**옵션 2: API 가져오기 사용**
+매우 큰 데이터셋의 경우 레코드 제한이 없는 API를 사용하세요.
+참고: [API로 데이터 가져오는 방법](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)
+
+---
+
+## 오류: 필드를 인식할 수 없음
+
+### 의미
+
+필드가 Twenty에 존재하지 않기 때문에 파일의 열을 매핑할 수 없습니다.
+
+### 해결 방법
+
+1. **설정 → 데이터 모델**로 이동
+2. 가져올 객체를 선택하세요
+3. **+ 필드 추가**를 클릭하세요
+4. 적절한 유형으로 커스텀 필드를 생성하세요
+5. 파일을 다시 업로드하세요
+
+<Note>CSV 가져오기는 필드가 아니라 레코드를 생성합니다. 가져오기 전에 모든 필드가 존재해야 합니다.</Note>
+
+---
+
+## 오류: 사용자 관계 비어 있음
+
+### 의미
+
+레코드를 사용자(소유자, 담당자)에게 할당하려고 하지만 관계가 매핑되지 않았습니다.
+
+### 일반적인 원인
+
+1. **사용자가 초대를 수락하지 않음** — 해당 사용자는 아직 Twenty에 존재하지 않음
+2. **이전 시스템의 사용자 ID 사용** — Twenty는 다른 시스템의 ID를 매칭할 수 없음
+3. **잘못된 이메일 형식** — 이메일이 사용자의 Twenty 계정과 일치하지 않음
+
+### 해결 방법
+
+1. 모든 사용자가 Twenty 워크스페이스 초대를 수락했는지 확인하세요
+2. 사용자의 이름이나 이전 시스템 ID가 아닌 **이메일 주소**를 사용하세요
+3. Twenty에 가입할 때 사용한 것과 동일한 이메일을 사용하세요
+
+<Warning>
+**가져오기를 진행하기 전에 사용자가 초대를 수락해야 합니다.**
+
+사용자가 초대를 수락하지 않은 경우, 해당 사용자를 참조하는 레코드의 사용자 관계가 비어 있게 됩니다.
+</Warning>
+
+---
+
+## 가져오기 전 체크리스트
+
+가져오기 전에 다음을 확인하여 오류를 방지하세요:
+
+### 파일 요구 사항
+
+<Check>파일 형식이 CSV, XLSX 또는 XLS임</Check>
+<Check>파일의 레코드가 10,000개 미만임</Check>
+<Check>파일이 UTF-8 인코딩을 사용함</Check>
+
+### 데이터 품질
+
+<Check>중복 이메일 없음(연락처용)</Check>
+<Check>중복 도메인 없음(회사용)</Check>
+<Check>모든 날짜가 일관된 형식을 사용</Check>
+<Check>모든 도메인이 `https://domain.com` 형식을 사용</Check>
+
+### 필드 형식
+
+<Check>불리언 필드는 `TRUE` 또는 `FALSE`(대문자) 사용</Check>
+<Check>선택 필드는 표시 라벨이 아닌 API 이름 사용</Check>
+<Check>전화 필드는 필요한 모든 열 포함</Check>
+<Check>통화 필드는 Amount와 Currency Code 모두 포함</Check>
+
+### 관계
+
+<Check>상위 레코드를 하위 레코드보다 먼저 가져오기</Check>
+<Check>관계 열이 기존 레코드를 참조</Check>
+<Check>도메인 형식이 Twenty의 형식과 정확히 일치</Check>
+
+### 데이터 모델
+
+<Check>모든 커스텀 필드가 설정 → 데이터 모델에 존재</Check>
+<Check>가져오기 전에 선택 옵션이 존재</Check>
+
+---
+
+## 아직도 문제가 있나요?
+
+위의 해결책을 시도했다면:
+
+1. **샘플 파일을 다운로드** — Twenty가 기대하는 정확한 형식을 확인하세요
+2. **기존 레코드를 내보내기** — 파일을 정상 데이터와 비교하세요
+3. **소량으로 테스트** — 먼저 5–10개의 행으로 시도하세요
+4. **참고 문서를 확인하세요:**
+   * [필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping)
+   * [고유성 제약 조건](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)
+   * [관계 가져오기](/l/ko/user-guide/data-migration/capabilities/import-relations)
+   * [오류 처리](/l/ko/user-guide/data-migration/capabilities/error-handling)

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/import-companies-via-csv.mdx

@@ -0,0 +1,201 @@
+---
+title: CSV로 회사 가져오기
+description: Twenty로 회사를 가져오는 포괄적인 단계별 가이드.
+---
+
+## 개요
+
+이 가이드는 회사를 Twenty로 가져오는 과정을 단계별로 안내합니다. **회사는 먼저 가져와야 합니다**. People과 Opportunities가 회사에 연결되기 때문입니다.
+
+## 시작하기 전에
+
+### 사전 준비 체크리스트
+
+<Check>
+파일이 CSV, XLSX 또는 XLS 형식임
+</Check>
+
+<Check>
+파일의 레코드가 10,000개 미만임
+</Check>
+
+<Check>
+파일에 중복된 도메인이 없음
+</Check>
+
+<Check>
+모든 사용자 정의 필드가 **Settings → Data Model**에 존재함
+</Check>
+
+<Note>
+10,000개 이상의 회사를 가져와야 하나요? 여러 파일로 분할하거나 [API 가져오기](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)를 사용하세요.
+</Note>
+
+## 1단계: 회사 데이터 준비
+
+### 필수 및 권장 필드
+
+| 필드            | 필수?   | 형식                   | 노트                 |
+| ------------- | ----- | -------------------- | ------------------ |
+| **Name**      | 권장    | 텍스트                  | 회사 표시 이름           |
+| **도메인**       | 권장    | `https://domain.com` | 고유 식별자             |
+| **주소**        | 선택 사항 | 여러 열                 | 아래 참조              |
+| **직원 수**      | 선택 사항 | 숫자                   | 직원 수               |
+| **사용자 정의 필드** | 선택 사항 | 항목에 따라 다름            | Data Model에 존재해야 함 |
+
+### 도메인 형식
+
+<Warning>
+**도메인에는 `https://domain.com` 형식을 사용하세요.**
+
+이는 이메일/캘린더 동기화로 회사가 자동 생성될 때 사용하는 형식과 일치하여, 이후 중복을 방지합니다.
+</Warning>
+
+**도메인 열:**
+
+* **Domain / Domain Label**: `acme.com`
+* **Domain / Domain URL**: `https://acme.com`
+
+### 주소 형식
+
+주소는 여러 열로 구성된 중첩 필드입니다:
+
+```
+Address / Address 1,Address / City,Address / State,Address / Country,Address / Post Code
+123 Main Street,San Francisco,CA,USA,94105
+```
+
+### CSV 예시 구조
+
+```csv
+name,Domain / Domain URL,Domain / Domain Label,Address / City,Address / Country,employees
+Acme Corp,https://acme.com,acme.com,San Francisco,USA,250
+Widget Co,https://widgets.co,widgets.co,New York,USA,50
+```
+
+<Note>
+**전문가 팁:** 가져오기 중에 **Download sample file**을 클릭하여 Twenty가 기대하는 정확한 열 이름을 확인하세요.
+</Note>
+
+## 2단계: 가져오기 기능에 액세스
+
+**옵션 1: Companies 보기에서**
+
+1. 왼쪽 사이드바에서 **Companies**로 이동하세요
+2. 오른쪽 상단의 **⋮** 아이콘을 클릭하세요
+3. **Import records**를 선택하세요
+
+**옵션 2: 커맨드 메뉴 사용**
+
+1. `Cmd + K`(Mac) 또는 `Ctrl + K`(Windows)를 누르세요
+2. "import"를 입력하세요
+3. **Import records**를 선택하세요
+4. **Companies**를 선택하세요
+
+## 3단계: 파일 업로드
+
+1. **Select file**을 클릭하세요
+2. CSV, XLSX 또는 XLS 파일을 선택하세요
+3. Twenty가 파일을 분석할 때까지 기다리세요
+
+## 4단계: 열 매핑
+
+Twenty가 열을 필드에 자동으로 매칭하려고 시도합니다. 검토 및 조정:
+
+1. **자동 매핑 확인** — 올바른지 확인하세요
+2. **잘못된 매핑 수정** — 드롭다운을 클릭하여 올바른 필드를 선택하세요
+3. **열 건너뛰기** — 가져오지 않을 열은 **Do not map**을 선택하세요
+
+### 중요한 매핑 규칙
+
+* **Domain**: **Domain / Domain URL**에 매핑하세요(Domain Label이 아님)
+* **Address**: 각 부분을 해당 열(City, State 등)에 매핑하세요
+* **선택 필드**: 값은 기존 옵션과 일치해야 합니다(또는 다음 단계에서 매핑하게 됩니다)
+
+<img src="/images/user-guide/import-export-data/match-columns.png" style={{width:'100%'}} />
+
+## 5단계: 선택 필드 값 매핑
+
+선택 또는 다중 선택 필드가 있는 경우:
+
+1. Twenty에서 사용자의 값을 기존 옵션과 나란히 표시합니다
+2. 파일의 각 값을 Twenty 옵션과 매칭하세요
+3. 필요하면 새 옵션을 만드세요
+
+<Note>
+선택 옵션은 표시 레이블이 아니라 **API 이름**을 사용합니다. API 이름을 보려면 **Settings → Data Model**에서 **Advanced mode**를 활성화하세요.
+</Note>
+
+## 6단계: 오류 검토 및 수정
+
+가져오기를 완료하기 전에 Twenty가 데이터를 검증합니다:
+
+1. **Next Steps**를 클릭하세요
+2. 오류가 있는 행은 **노란색**으로 강조 표시됩니다
+3. **오류를 직접 수정** — 셀을 클릭하고 값을 편집하세요
+4. **문제가 있는 행 제거** — 해당 행을 건너뛰려면 X를 클릭하세요
+
+### 일반적인 회사 가져오기 오류
+
+| 오류             | 원인                  | 해결책                         |
+| -------------- | ------------------- | --------------------------- |
+| **중복 도메인**     | 도메인이 Twenty에 이미 존재함 | 파일에서 제거하거나 기존 레코드를 업데이트하세요  |
+| **잘못된 도메인 형식** | 잘못된 형식              | `https://domain.com`을 사용하세요 |
+| **필수 필드 누락**   | 필수 필드가 비어 있음        | 값을 입력하거나 해당 행을 제거하세요        |
+
+## 7단계: 가져오기 완료
+
+1. 가져오기 요약을 검토하세요
+2. 가져오려면 **확인**을 클릭하세요
+3. 가져오기가 완료될 때까지 기다리세요
+4. 몇 개의 레코드를 확인하여 검증하세요
+
+## 회사 가져오기 후
+
+이제 회사에 연결되는 레코드를 가져올 수 있습니다:
+
+1. **[연락처 가져오기](/l/ko/user-guide/data-migration/how-tos/import-contacts-via-csv)** — 도메인을 사용하여 회사에 연결하세요
+2. **기회 가져오기** — 회사에 연결하세요
+3. **가져오기를 검증** — 데이터가 올바른지 확인하기 위해 몇 개의 레코드를 샘플로 점검하세요
+
+## 기존 회사 업데이트
+
+새로 생성하는 대신 회사를 업데이트하려면:
+
+1. 파일에 `domain` 또는 `id` 열을 포함하세요
+2. Twenty는 이 고유 식별자로 레코드를 매칭합니다
+3. 기존 회사는 업데이트되고, 새 회사는 생성됩니다
+
+자세한 내용은 [기존 레코드를 업데이트하는 방법](/l/ko/user-guide/data-migration/how-tos/update-existing-records-via-import)을 참조하세요.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="왜 두 회사가 동일한 도메인을 가질 수 없나요?">
+    도메인은 Twenty에서 고유 식별자입니다. 이는 중복 회사를 방지하고 이메일 동기화가 올바른 회사에 이메일을 정확히 연결되도록 보장합니다.
+  </Accordion>
+
+  <Accordion title="도메인이 없는 회사가 있으면 어떻게 하나요?">
+    도메인을 비워둘 수 있습니다. 하지만 더 나은 데이터 품질과 자동 이메일 연결을 위해 가능하면 도메인을 추가할 것을 권장합니다.
+  </Accordion>
+
+  <Accordion title="People이 연결되지 않은 회사를 가져올 수 있나요?">
+    예! 먼저 회사를 가져온 다음, 이후 개인을 가져와 회사 도메인을 사용해 서로 연결할 수 있습니다.
+  </Accordion>
+
+  <Accordion title="이미 존재하는 도메인을 가져오면 어떻게 되나요?">
+    기존 회사와 일치하는 고유 식별자(도메인 또는 id)를 포함하면, Twenty는 중복을 생성하는 대신 해당 회사를 업데이트합니다.
+  </Accordion>
+
+  <Accordion title="'duplicate domain' 오류는 어떻게 해결하나요?">
+    파일에서 중복을 제거하거나, 회사의 `id`를 포함하여 기존 레코드를 업데이트하세요.
+  </Accordion>
+</AccordionGroup>
+
+## 문제 해결
+
+문제가 있으신가요? 확인하세요:
+
+* [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)
+* [필드 매핑 레퍼런스](/l/ko/user-guide/data-migration/capabilities/field-mapping)
+* [고유성 제약 조건](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/import-contacts-via-csv.mdx

@@ -0,0 +1,242 @@
+---
+title: CSV로 연락처 가져오기
+description: Twenty로 사람/연락처를 가져오는 포괄적인 단계별 가이드.
+---
+
+## 개요
+
+이 가이드는 연락처(People)를 Twenty로 가져오는 과정을 단계별로 안내합니다.
+
+## 시작하기 전에
+
+### 사전 준비 체크리스트
+
+<Check>
+파일이 CSV, XLSX 또는 XLS 형식임
+</Check>
+
+<Check>
+파일의 레코드가 10,000개 미만임
+</Check>
+
+<Check>
+파일에 중복된 이메일 주소가 없음
+</Check>
+
+<Check>
+**회사를 먼저 가져옴**(사람을 회사에 연결하는 경우)
+</Check>
+
+<Check>
+모든 사용자 정의 필드가 **Settings → Data Model**에 존재함
+</Check>
+
+<Warning>
+**사람보다 회사를 먼저 가져오기**
+
+사람을 회사에 연결하려면 먼저 회사를 가져오세요. 참조하려면 회사가 먼저 존재해야 합니다.
+</Warning>
+
+## 1단계: 연락처 데이터 준비
+
+### 필수 및 권장 필드
+
+| 필드            | 필수?   | 형식                | 노트                 |
+| ------------- | ----- | ----------------- | ------------------ |
+| **이메일**       | 권장    | `name@domain.com` | 고유해야 함             |
+| **이름**        | 권장    | 텍스트               |                    |
+| **성**         | 권장    | 텍스트               |                    |
+| **회사**        | 선택 사항 | 도메인 또는 ID         | 기존 회사에 연결          |
+| **전화**        | 선택 사항 | 여러 열              | 아래 참조              |
+| **직책**        | 선택 사항 | 텍스트               |                    |
+| **사용자 정의 필드** | 선택 사항 | 항목에 따라 다름         | Data Model에 존재해야 함 |
+
+### 이메일 형식
+
+* 유효한 이메일 형식이어야 함: `name@domain.com`
+* **고유해야 함** — 파일 또는 Twenty에 중복이 없어야 합니다
+* 추가 이메일은 **Emails / Additional Emails** 열을 사용하세요:
+
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### 전화 형식
+
+전화는 여러 열이 필요한 **중첩 필드**입니다:
+
+| 열                                       | 예시           |
+| --------------------------------------- | ------------ |
+| **Phones / Primary Phone Number**       | `4159095555` |
+| **Phones / Primary Phone Country Code** | `US`         |
+| **Phones / Primary Phone Calling Code** | `+1`         |
+
+### 회사에 연결하기
+
+회사 고유 식별자 열을 추가하세요:
+
+| 열 이름            | 형식     | 예시                                     |
+| --------------- | ------ | -------------------------------------- |
+| `companyDomain` | URL 형식 | `https://acme.com`                     |
+| `companyId`     | UUID   | `c776ee49-f608-4a77-8cc8-6fe96ae1e43f` |
+
+<Note>
+**도메인 URL 형식을 사용하세요**(`https://acme.com`), 라벨은 사용하지 마세요. 이는 Twenty에서 회사가 저장되는 방식과 일치합니다.
+</Note>
+
+### CSV 예시 구조
+
+```csv
+firstName,lastName,email,jobTitle,companyDomain,Phones / Primary Phone Number,Phones / Primary Phone Country Code
+John,Smith,john@acme.com,CEO,https://acme.com,4159095555,US
+Jane,Doe,jane@widgets.co,CTO,https://widgets.co,2125551234,US
+```
+
+<Note>
+**전문가 팁:** 가져오기 중에 **Download sample file**을 클릭하거나 기존 People 몇 명을 내보내 Twenty가 기대하는 정확한 열 이름을 확인하세요.
+</Note>
+
+## 2단계: 가져오기 기능에 액세스
+
+**옵션 1: People 보기에서**
+
+1. 왼쪽 사이드바에서 **People**로 이동하세요
+2. 오른쪽 상단의 **⋮** 아이콘을 클릭하세요
+3. **Import records**를 선택하세요
+
+**옵션 2: 커맨드 메뉴 사용**
+
+1. `Cmd + K`(Mac) 또는 `Ctrl + K`(Windows)를 누르세요
+2. "import"를 입력하세요
+3. **Import records**를 선택하세요
+4. **People**을 선택하세요
+
+## 3단계: 파일 업로드
+
+1. **Select file**을 클릭하세요
+2. CSV, XLSX 또는 XLS 파일을 선택하세요
+3. Twenty가 파일을 분석할 때까지 기다리세요
+
+## 4단계: 열 매핑
+
+Twenty가 열을 필드에 자동으로 매칭하려고 시도합니다. 검토 및 조정:
+
+1. **자동 매핑 확인** — 올바른지 검증하세요
+2. **잘못된 매핑 수정** — 드롭다운을 클릭하여 올바른 필드를 선택하세요
+3. **열 건너뛰기** — 가져오지 않을 열은 **Do not map**을 선택하세요
+
+### 중요한 매핑 규칙
+
+| 열 유형   | 매핑 대상                          | 노트                              |
+| ------ | ------------------------------ | ------------------------------- |
+| 회사 참조  | **회사** 관계 필드                   | 도메인 또는 ID 중 하나만 사용(둘 다 사용하지 않음) |
+| 이메일    | **이메일**                        | 기본 이메일 주소                       |
+| 추가 이메일 | **Emails / Additional Emails** | 배열 형식                           |
+| 전화     | 분리된 열                          | 번호, 국가 코드, 전화 걸기 코드             |
+
+<img src="/images/user-guide/import-export-data/match-columns.png" style={{width:'100%'}} />
+
+### 회사 관계 매핑
+
+회사 열을 매핑할 때:
+
+1. 회사 참조 열을 찾으세요(예: `companyDomain`)
+2. 이를 **회사** 관계 필드에 매핑하세요
+3. Twenty가 각 사람을 일치하는 회사에 연결합니다
+
+<Warning>
+**관계에는 고유 식별자를 하나만 매핑하세요.**
+
+`companyId`와 `companyDomain`을 둘 다 매핑하지 마세요. 하나만 선택하세요—사람이 읽기 쉬우므로 도메인을 권장합니다.
+</Warning>
+
+## 5단계: 선택 필드 값 매핑
+
+선택 또는 다중 선택 필드(예: 리드 소스)가 있는 경우:
+
+1. Twenty에서 사용자의 값을 기존 옵션과 나란히 표시합니다
+2. 파일의 각 값을 Twenty 옵션과 매칭하세요
+3. 필요하면 새 옵션을 만드세요
+
+<Note>
+선택 옵션은 표시 레이블이 아니라 **API 이름**을 사용합니다. API 이름을 보려면 **Settings → Data Model**에서 **Advanced mode**를 활성화하세요.
+</Note>
+
+## 6단계: 오류 검토 및 수정
+
+가져오기를 완료하기 전에 Twenty가 데이터를 검증합니다:
+
+1. **다음 단계**를 클릭합니다
+2. 오류가 있는 행은 **노란색**으로 강조 표시됩니다
+3. **오류를 직접 수정** — 셀을 클릭하고 값을 편집하세요
+4. **문제가 있는 행 제거** — 해당 행을 건너뛰려면 X를 클릭하세요
+
+### 일반적인 연락처 가져오기 오류
+
+| 오류              | 원인                        | 해결책                       |
+| --------------- | ------------------------- | ------------------------- |
+| **중복 이메일**      | 이메일이 Twenty 또는 파일에 이미 존재함 | 중복을 제거하거나 기존 레코드를 업데이트하세요 |
+| **잘못된 이메일 형식**  | 이메일 형식이 올바르지 않음           | `name@domain.com`으로 수정하세요 |
+| **관계를 찾을 수 없음** | 회사가 존재하지 않음               | 먼저 회사를 가져오거나 참조를 수정하세요    |
+| **필수 필드 누락**    | 필수 필드가 비어 있음              | 값을 입력하거나 해당 행을 제거하세요      |
+
+## 7단계: 가져오기 완료
+
+1. 가져오기 요약을 검토하세요
+2. 가져오려면 **확인**을 클릭합니다
+3. 가져오기가 완료될 때까지 기다리세요
+4. 몇 개의 레코드와 해당 회사 링크를 확인하여 검증하세요
+
+## 연락처 가져오기 후
+
+이제 연락처가 Twenty에 있습니다! 다음 단계:
+
+1. **회사 링크 확인** — 올바른 회사에 연결되어 있는지 확인하려면 몇 개의 연락처 레코드를 여세요
+2. **기회 가져오기** — 필요한 경우 연락처 및 회사에 연결하세요
+3. **이메일 동기화 설정** — 연락처 레코드에서 이메일 내역을 볼 수 있도록 메일박스를 연결하세요
+
+## 기존 연락처 업데이트
+
+새로 생성하는 대신 연락처를 업데이트하려면:
+
+1. 파일에 `email` 또는 `id` 열을 포함하세요
+2. Twenty는 이 고유 식별자로 레코드를 매칭합니다
+3. 기존 연락처는 업데이트되고, 새 연락처는 생성됩니다
+
+자세한 내용은 [기존 레코드를 업데이트하는 방법](/l/ko/user-guide/data-migration/how-tos/update-existing-records-via-import)을 참조하세요.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="왜 두 연락처가 동일한 이메일을 가질 수 없나요?">
+    이메일은 Twenty에서 고유 식별자입니다. 이는 중복 연락처를 방지하고 이메일 동기화가 올바른 연락처에 이메일을 정확히 연결되도록 보장합니다.
+  </Accordion>
+
+  <Accordion title="이메일이 없는 연락처가 있으면 어떻게 하나요?">
+    이메일을 비워둘 수 있습니다. 하지만 데이터 품질과 이메일 동기화 기능을 위해 가능하면 이메일을 추가할 것을 권장합니다.
+  </Accordion>
+
+  <Accordion title="가져오기 중 연락처를 회사에 어떻게 연결하나요?">
+    회사의 도메인(예: `https://acme.com`) 또는 ID가 포함된 열을 추가하세요. 매핑 중에 이 열을 회사 관계 필드에 연결하세요.
+  </Accordion>
+
+  <Accordion title="회사가 아직 존재하지 않으면 어떻게 하나요?">
+    먼저 회사를 가져오고, 그다음 연락처를 가져오세요. 참조하려면 해당 회사가 먼저 존재해야 합니다.
+  </Accordion>
+
+  <Accordion title="이전 CRM의 ID를 가져올 수 있나요?">
+    예! 외부 ID를 저장하려면 데이터 모델에 "unique"로 표시된 사용자 지정 필드를 만드세요. 참고: 필드 이름 `id`는 Twenty의 내부 ID로 예약되어 있습니다.
+  </Accordion>
+
+  <Accordion title="'relation not found' 오류는 어떻게 해결하나요?">
+    참조하려는 회사가 존재하지 않습니다. 회사를 먼저 가져오거나, 도메인/ID가 기존 회사와 정확히 일치하는지 확인하세요.
+  </Accordion>
+</AccordionGroup>
+
+## 문제 해결
+
+문제가 있으신가요? 확인하세요:
+
+* [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)
+* [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)
+* [필드 매핑 레퍼런스](/l/ko/user-guide/data-migration/capabilities/field-mapping)

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/import-data-via-api.mdx

@@ -0,0 +1,176 @@
+---
+title: API로 데이터 가져오기
+description: 대규모 데이터 가져오기에 Twenty의 API를 언제, 어떻게 사용할지 안내합니다.
+---
+
+## 개요
+
+Twenty는 프로그램 방식의 데이터 가져오기를 위해 **GraphQL** 및 **REST API**를 모두 제공합니다. 데이터 규모상 CSV 가져오기가 실용적이지 않거나 자동화된 반복 가져오기가 필요한 경우 API를 사용하세요.
+
+## API 가져오기 사용 시기
+
+| 시나리오                 | 권장 방법            |
+| -------------------- | ---------------- |
+| 10,000개 미만의 레코드      | CSV 가져오기         |
+| 10,000 - 50,000개 레코드 | CSV 가져오기(파일로 분할) |
+| **50,000개 이상의 레코드**  | **API 가져오기**     |
+| 1회성 마이그레이션           | 둘 다 가능(규모에 따라)   |
+| **반복 가져오기**          | **API 가져오기**     |
+| **실시간 동기화**          | **API 가져오기**     |
+| **다른 시스템과의 통합**      | **API 가져오기**     |
+
+<Note>수십만 건 규모의 데이터셋의 경우, API가 여러 번의 CSV 가져오기보다 훨씬 빠르고 더 신뢰할 수 있습니다.</Note>
+
+## API 속도 제한
+
+시스템 안정성을 보장하기 위해 Twenty는 속도 제한을 적용합니다:
+
+| 제한               | 값            |
+| ---------------- | ------------ |
+| **분당 요청 수**      | 100          |
+| **배치 호출당 레코드 수** | 60           |
+| **최대 처리량**       | ~6,000 레코드/분 |
+
+<Warning>
+**이 한도를 기준으로 가져오기 계획을 수립하세요.**
+
+최대 처리량 기준으로 100,000개 레코드를 가져오는 데 약 17분이 소요됩니다. 오류 처리와 재시도를 위한 여유 시간을 추가하세요.
+</Warning>
+
+## 시작하기
+
+### 1단계: API 키 받기
+
+1. **설정 → 개발자**로 이동하세요.
+2. **+ API 키 생성**을 클릭하세요.
+3. 키에 설명적인 이름을 지정하세요.
+4. API 키를 즉시 복사하세요(다시 표시되지 않습니다).
+5. 안전하게 보관하세요.
+
+<Warning>
+**API 키를 비공개로 유지하세요.**
+
+API 키를 가진 누구나 워크스페이스 데이터에 접근하고 수정할 수 있습니다. 코드 저장소에 커밋하거나 공개적으로 공유하지 마세요.
+</Warning>
+
+### 2단계: 사용할 API 선택
+
+Twenty는 두 가지 유형의 API를 지원합니다:
+
+| API         | 적합한 용도                        | 문서                               |
+| ----------- | ----------------------------- | -------------------------------- |
+| **GraphQL** | 유연한 쿼리, 연관 데이터 조회, 복잡한 작업에 적합 | [API 문서](/l/ko/developers/extend/api) |
+| **REST**    | 단순한 CRUD 작업, 익숙한 REST 패턴      | [API 문서](/l/ko/developers/extend/api) |
+
+두 API 모두 다음을 지원합니다:
+
+* 레코드 생성, 조회, 업데이트 및 삭제
+* **배치 작업** — 호출당 최대 60개 레코드를 생성하거나 업데이트
+
+**가져오기에서는 배치 작업을 사용**하여 한도 내에서 처리량을 극대화하세요.
+
+### 3단계: 가져오기 순서 계획
+
+CSV 가져오기와 마찬가지로, 관계형 데이터에서는 **순서가 중요**합니다:
+
+1. **회사** 먼저(종속성 없음)
+2. 그다음 **사람**(회사에 연결 가능)
+3. 세 번째로 **기회**(회사 및 사람에 연결 가능)
+4. **작업/노트**(위 항목 중 어느 것에도 연결 가능)
+5. **사용자 지정 객체**(종속성을 따름)
+
+## 모범 사례
+
+### 요청 일괄 처리
+
+* 레코드를 한 번에 하나씩 보내지 마세요
+* API 호출당 최대 **60개 레코드**로 묶으세요
+* 이렇게 하면 한도 내에서 처리량을 극대화할 수 있습니다
+
+### 속도 제한 처리
+
+* 요청 사이에 지연을 구현하세요(지속적인 가져오기의 경우 최소 600ms)
+* 한도에 도달하면 지수 백오프를 사용하세요
+* 429(Too Many Requests) 응답을 모니터링하세요
+
+### 먼저 데이터 검증
+
+* 가져오기 전에 데이터를 정리하고 검증하세요
+* 필수 필드가 채워졌는지 확인하세요
+* 형식이 Twenty의 요구 사항과 일치하는지 확인하세요([필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping) 참조)
+
+### 모든 항목 로깅
+
+* 가져온 모든 레코드를 로깅하세요(ID 포함)
+* 전체 컨텍스트와 함께 오류를 로깅하세요
+* 이는 문제를 디버깅하고 완료 여부를 확인하는 데 도움이 됩니다
+
+### 먼저 테스트
+
+* 소량 배치(10-20개 레코드)로 테스트하세요
+* 데이터가 Twenty에 올바르게 표시되는지 확인하세요
+* 그런 다음 전체 가져오기를 실행하세요
+
+### 중복 방지를 위한 업서트
+
+GraphQL API는 **배치 업서트**를 지원합니다 — 레코드가 있으면 업데이트하고, 없으면 생성합니다. 이렇게 하면 가져오기를 다시 실행할 때 중복을 방지할 수 있습니다.
+
+## 객체 및 필드 이름 찾기
+
+사용 가능한 객체와 필드를 확인하려면:
+
+1. **설정 → API 및 웹훅**으로 이동하세요
+2. **Metadata API**를 살펴보세요
+3. 모든 표준 및 사용자 지정 객체와 해당 필드를 확인하세요
+
+문서에는 모든 표준 및 사용자 지정 객체, 해당 필드, 예상 데이터 유형이 표시됩니다.
+
+## 전문 서비스
+
+복잡한 API 마이그레이션의 경우, 파트너가 도와드립니다:
+
+| 서비스             | 포함 내용              |
+| --------------- | ------------------ |
+| **데이터 모델 설계**   | 최적의 데이터 구조를 설계     |
+| **마이그레이션 스크립트** | 가져오기 스크립트를 작성하고 실행 |
+| **데이터 변환**      | 복잡한 매핑과 정리를 수행     |
+| **검증 및 QA**     | 마이그레이션이 완료되었는지 확인  |
+
+**적합한 용도:**
+
+* 100,000개 이상의 레코드 마이그레이션
+* 복잡한 데이터 변환
+* 빠듯한 일정
+* 개발 리소스가 없는 팀
+
+[contact@twenty.com](mailto:contact@twenty.com)으로 문의하시거나 당사의 [구현 서비스](/l/ko/user-guide/getting-started/capabilities/implementation-services)를 확인하세요.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="GraphQL과 REST의 차이는 무엇인가요?">
+    GraphQL은 단일 쿼리로 필요한 데이터만 정확히 요청할 수 있으며, 복잡한 작업에 더 적합합니다. REST는 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하며, 기존 API로 작업해 본 경험이 있다면 더 익숙할 수 있습니다.
+  </Accordion>
+
+  <Accordion title="API를 통해 기존 레코드를 업데이트할 수 있나요?">
+    예! 레코드의 `id`와 함께 업데이트 뮤테이션(GraphQL) 또는 PUT/PATCH 요청(REST)을 사용하세요.
+  </Accordion>
+
+  <Accordion title="중복은 어떻게 처리하나요?">
+    고유 식별자(이메일, 도메인)를 사용해 먼저 기존 레코드를 조회하세요. 존재하면 업데이트하고, 없으면 생성하세요.
+  </Accordion>
+
+  <Accordion title="API를 통해 레코드를 삭제할 수 있나요?">
+    예, 삭제 뮤테이션(GraphQL) 또는 DELETE 요청(REST)을 사용하세요.
+  </Accordion>
+
+  <Accordion title="Python 또는 Node.js SDK가 있나요?">
+    현재는 없습니다. 하지만 두 API는 어떤 언어의 HTTP 클라이언트와도 작동합니다.
+  </Accordion>
+</AccordionGroup>
+
+## API 문서
+
+전체 구현 세부정보, 코드 예제, 스키마 참조는 다음을 확인하세요:
+
+* [API 문서](/l/ko/developers/extend/api)

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv.mdx

@@ -0,0 +1,225 @@
+---
+title: CSV를 통해 객체 간 관계 가져오기
+description: CSV 가져오기 중 레코드 연결에 대한 완전한 단계별 가이드.
+---
+
+## 개요
+
+이 가이드는 객체 간 관계를 가져오는 방법을 안내합니다—예를 들어, 사람을 회사에 연결하거나 기회를 사람에게 연결하는 방법.
+
+<Note>**가져올 수 있는 항목:** 단일 객체 유형을 가리키는 일대다 관계만 가능합니다. 여러 객체 유형을 가리키는 관계(예: 노트가 사람과 회사 모두에 연결)는 아직 가져오기를 지원하지 않습니다.</Note>
+
+## 관계 이해하기
+
+### "일대다" 관계란?
+
+일대다 관계에서는:
+
+* **하나의** 회사에는 **여러** 사람(직원)이 있습니다
+* **하나의** 회사에는 **여러** 기회가 있습니다
+* **한** 사람에게는 **여러** 작업이 있습니다
+
+"one" 쪽은 **상위**입니다. "many" 쪽은 **하위**입니다.
+
+### Twenty에서 흔한 관계
+
+| 관계      | "One" 쪽(상위) | "Many" 쪽(하위) |
+| ------- | ----------- | ------------ |
+| 회사 → 사람 | 회사          | 사람들          |
+| 회사 → 기회 | 회사          | 기회           |
+| 사람 → 작업 | 사람          | 작업           |
+| 사람 → 노트 | 사람          | 노트           |
+
+## 1단계: "One"과 "Many" 쪽 식별하기
+
+가져오기 전에 어떤 객체가 상위이고 어떤 객체가 하위인지 결정하세요.
+
+**스스로에게 물어보세요:** "하나의 [객체 A]가 여러 [객체 B]를 가지는가?"
+
+* 하나의 회사 → 여러 사람 ✓ (회사가 상위)
+* 한 사람 → 여러 회사 ✗ (잘못된 예—사람은 한 회사에 소속됩니다)
+
+## 2단계: 상위 레코드를 먼저 가져오기
+
+참조하려면 상위("one" 쪽) 레코드가 Twenty에 먼저 존재해야 합니다.
+
+**가져오기 순서:**
+
+1. **회사** 먼저(종속성 없음)
+2. 그다음 **사람**(회사에 연결)
+3. 세 번째로 **기회**(회사 및/또는 사람에 연결)
+4. **작업/노트**(위 항목 중 하나에 연결)
+
+<Warning>
+**상위 레코드가 존재하지 않으면 가져오기는 실패합니다.**
+
+회사 참조가 있는 사람을 가져오기 전에 항상 회사를 먼저 가져왔는지 확인하세요.
+</Warning>
+
+## 3단계: 상위의 고유 식별자 확인
+
+**고유 식별자**를 사용해 상위 레코드를 참조해야 합니다. 사용 가능한 옵션:
+
+| 상위 객체          | 사용 가능한 고유 식별자                             |
+| -------------- | ----------------------------------------- |
+| **회사**         | `id`(UUID), `domain`(권장), 또는 사용자 지정 고유 필드 |
+| **사람들**        | `id`(UUID), `email`, 또는 사용자 지정 고유 필드      |
+| **워크스페이스 멤버들** | `id`(UUID), `email`(이름 아님)                |
+| **사용자 지정 개체**  | `id`(UUID), 또는 고유로 표시된 모든 필드              |
+
+<Note>**권장:** 회사에는 `domain`, 사람에는 `email`을 사용하세요. 이들은 사람이 읽기 쉬우며 스프레드시트에서 확인하기도 쉽습니다.</Note>
+
+### 식별자 찾기
+
+`id`가 필요하다면:
+
+1. Twenty에서 상위 레코드를 내보내세요
+2. 내보내기에는 `id` 열이 포함됩니다
+3. 이 ID를 하위 레코드 파일에서 사용하세요
+
+## 4단계: 관계 필드가 존재하는지 확인
+
+가져오기 전에 객체 간에 관계 필드가 존재하는지 확인하세요.
+
+**확인 또는 생성 방법:**
+
+1. **설정 → 데이터 모델**로 이동
+2. 하위 객체를 선택하세요(예: 사람)
+3. 상위를 가리키는 관계 필드를 찾으세요(예: 회사)
+4. 없다면 다음과 같이 생성하세요:
+   * **+ 필드 추가**를 클릭하세요
+   * 필드 유형으로 **관계**를 선택하세요
+   * 상위 객체를 선택하세요
+
+## 5단계: CSV 파일 준비
+
+하위 CSV에 상위의 고유 식별자를 사용해 상위를 참조하는 열을 추가하세요.
+
+### 예: 사람 → 회사 연결
+
+**사람 CSV:**
+
+```csv
+firstName,lastName,email,jobTitle,companyDomain
+John,Smith,john@acme.com,CEO,https://acme.com
+Jane,Doe,jane@widgets.co,CTO,https://widgets.co
+Bob,Johnson,bob@techstart.io,Developer,https://techstart.io
+```
+
+`companyDomain` 열은 회사의 도메인을 참조합니다.
+
+### 형식 요구 사항
+
+| 식별자 | 형식     | 예시                                     |
+| --- | ------ | -------------------------------------- |
+| 도메인 | URL 형식 | `https://acme.com`                     |
+| 이메일 | 표준 이메일 | `john@acme.com`                        |
+| ID  | UUID   | `c776ee49-f608-4a77-8cc8-6fe96ae1e43f` |
+
+<Warning>
+**도메인 형식이 중요합니다!**
+
+`https://domain.com`을 사용하세요(`domain.com`만 사용하지 마세요). 이는 Twenty가 회사 도메인을 저장하는 방식과 일치하며, 매칭 오류를 방지합니다.
+</Warning>
+
+### 중요 규칙
+
+1. **정확히 일치해야 함** — 값이 상위 레코드와 정확히 일치해야 합니다
+2. **고유 식별자는 하나만 매핑** — `companyId`와 `companyDomain`을 모두 포함하지 마세요
+3. **대소문자 구분** — `Acme.com` ≠ `acme.com`
+
+## 6단계: 업로드하고 관계 매핑하기
+
+1. 하위 객체로 이동하세요(예: 사람)
+2. **⋮** → **레코드 가져오기**를 클릭
+3. CSV 파일을 업로드하세요
+4. 필드 매핑 단계에서:
+   * 관계 열을 찾으세요(예: `companyDomain`)
+   * 이를 **회사** 관계 필드에 매핑하세요
+5. 나머지 매핑을 완료하세요
+6. 오류를 검토하고 확인하세요
+
+Twenty가 각 하위 레코드를 일치하는 상위에 자동으로 연결합니다.
+
+## 7단계: 가져오기 확인
+
+가져온 후:
+
+1. 하위 레코드 몇 개를 엽니다(예: 사람)
+2. 관계 필드에 올바른 상위(예: 회사)가 표시되는지 확인하세요
+3. 상위 레코드를 열고 관련 레코드 섹션을 확인하세요
+
+## 피해야 할 일반적인 실수
+
+| 실수              | 문제                                    | 해결책                              |
+| --------------- | ------------------------------------- | -------------------------------- |
+| **잘못된 가져오기 순서** | 회사보다 사람을 먼저 가져오기                      | 항상 상위를 먼저, 그다음 하위를 가져오세요         |
+| **잘못된 도메인 형식**  | `https://acme.com` 대신 `acme.com`을 사용함 | `https://`가 포함된 전체 URL 형식을 사용하세요 |
+| **여러 개의 고유 필드** | `companyId`와 `companyDomain`을 둘 다 매핑함 | 고유 식별자를 하나만 매핑하세요                |
+| **관계 필드 누락**    | 데이터 모델에 관계 필드가 존재하지 않음                | 가져오기 전에 **설정 → 데이터 모델**에서 생성하세요  |
+| **존재하지 않는 레코드** | 상위 레코드가 Twenty에 존재하지 않음               | 상위 레코드를 먼저 가져오거나, 오타를 확인하세요      |
+| **대소문자 불일치**    | 파일에는 `Acme.com`, Twenty에는 `acme.com`  | 대소문자가 정확히 일치하는지 확인하세요            |
+
+## 워크스페이스 구성원에 연결하기
+
+워크스페이스 구성원(팀원)에 연결할 때:
+
+* 이름이 아니라 **이메일 주소**를 사용하세요
+* 예: `owner@yourcompany.com`, "John Smith"가 아님
+
+```csv
+taskName,assignedTo
+Follow up with client,john@yourcompany.com
+Review proposal,jane@yourcompany.com
+```
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="상위 레코드에 도메인이나 이메일이 없으면 어떻게 하나요?">
+    다음 두 가지 옵션이 있습니다:
+    1. Twenty의 `id`를 사용하세요(상위 레코드를 내보내 ID를 가져오세요)
+    2. 데이터 모델에 사용자 지정 고유 필드를 만들어 이전 시스템의 외부 ID를 저장하세요
+  </Accordion>
+
+  <Accordion title="기존 레코드의 관계를 업데이트할 수 있나요?">
+    예! 하위 레코드의 고유 식별자(예: 사람의 경우 `email`)와 새로운 관계 값을 포함하세요. 가져오기가 관계를 업데이트합니다.
+  </Accordion>
+
+  <Accordion title="다대다 관계를 가져올 수 있나요?">
+    다대다 관계는 아직 가져오기를 지원하지 않습니다. 이는 2026년 상반기에 계획되어 있습니다.
+  </Accordion>
+
+  <Accordion title="여러 객체 유형(예: 노트를 사람과 회사 모두)에 연결할 수 있나요?">
+    여러 객체 유형을 가리키는 관계는 아직 가져오기/내보내기를 지원하지 않습니다. 이는 로드맵에 포함되어 있습니다.
+  </Accordion>
+
+  <Accordion title="상위 레코드가 존재하지 않으면 어떻게 되나요?">
+    해당 행에 대해 가져오기가 오류를 표시합니다. 다음 두 가지 방법 중 하나로 가능합니다:
+    * 상위 레코드를 먼저 가져온 뒤 다시 가져오세요
+    * 참조 값을 수정하세요
+    * 가져오기에서 해당 행을 제거하세요
+  </Accordion>
+
+  <Accordion title="관계가 올바르게 연결되지 않는 이유는 무엇인가요?">
+    일반적인 원인:
+    * 잘못된 형식(도메인은 `https://domain.com`을 사용)
+    * 대소문자 불일치(정확한 철자 확인)
+    * 상위가 존재하지 않음(상위를 먼저 가져오기)
+    * 여러 식별자 매핑(하나만 사용)
+  </Accordion>
+</AccordionGroup>
+
+<Warning>
+**기억하세요: 소프트 삭제된 레코드도 고유성에 포함됩니다.**
+
+레코드가 존재하는 것처럼 보이는데도 "not found" 오류가 발생한다면, Command Menu → See deleted records를 확인하세요. 상위가 소프트 삭제되었을 수 있습니다.
+</Warning>
+
+## 문제 해결
+
+문제가 있으신가요? 확인하세요:
+
+* [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)
+* [관계 가져오기 기능](/l/ko/user-guide/data-migration/capabilities/import-relations)
+* [고유성 제약 조건](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/migrating-from-other-crms.mdx

@@ -0,0 +1,289 @@
+---
+title: 다른 CRM에서 마이그레이션하기
+description: 어떤 CRM에서든 데이터를 Twenty로 마이그레이션하는 단계별 가이드.
+---
+
+## 개요
+
+이 가이드는 어떤 CRM에서든 데이터를 Twenty로 마이그레이션하는 과정을 단계별로 안내합니다. 이 과정에는 데이터 감사, Twenty 워크스페이스 준비, 현재 시스템에서의 내보내기, Twenty로의 가져오기가 포함됩니다.
+
+<Note>마이그레이션 후에는 뷰, 워크플로우, 권한을 수동으로 다시 만들어야 합니다. 이 구성 작업에 필요한 시간을 계획하세요.</Note>
+
+## 1단계: 현재 데이터 감사
+
+마이그레이션은 새롭게 시작할 수 있는 기회입니다. 불필요한 데이터는 가져오지 마세요.
+
+**유지할 항목:**
+
+* 활성 연락처 및 회사
+* 열려 있는 기회와 거래
+* 중요한 메모와 활동
+* 실제로 사용하는 사용자 정의 필드
+
+**남겨둘 항목:**
+
+* 오래된 연락처(2년 이상 활동 없음)
+* 중복 레코드
+* 테스트 데이터
+* 사용하지 않는 사용자 정의 필드
+
+## 2단계: 데이터 모델 매핑
+
+현재 CRM과 Twenty 간의 매핑 문서를 만드세요:
+
+| 현재 CRM    | Twenty           |
+| --------- | ---------------- |
+| 계정 / 조직   | **회사**           |
+| 연락처 / 개인  | **사람들**          |
+| 거래 / 기회   | **기회**           |
+| 활동        | **작업** 또는 **노트** |
+| 사용자 지정 개체 | **사용자 지정 개체**    |
+
+**각 필드에 대해 다음을 문서화합니다:**
+
+* 원본 필드 이름
+* 대상 Twenty 필드
+* 필요한 형식 변환(날짜, 전화번호 등)
+
+<Note>가져오기 중에 이 매핑 문서를 가까이 두세요—열을 매핑할 때 참고하게 됩니다.</Note>
+
+## 3단계: Twenty 워크스페이스 설정
+
+데이터를 가져오기 전에 Twenty 워크스페이스를 준비하세요:
+
+### 사용자 지정 개체 및 필드 만들기
+
+1. **설정 → 데이터 모델**로 이동
+2. 필요한 사용자 지정 개체를 생성하세요
+3. 표준 개체와 사용자 지정 개체에 사용자 지정 필드를 추가하세요
+4. 필드 설정(고유, 필수, 선택 옵션 등)을 구성하세요
+
+<Warning>
+**가져오기 전에 필드가 존재해야 합니다.**
+
+CSV 가져오기는 필드가 아니라 레코드를 생성합니다. 가져오기 전에 **설정 → 데이터 모델**에서 사용자 지정 필드를 생성하세요.
+</Warning>
+
+### 팀 초대
+
+<Warning>
+**데이터를 가져오기 전에 사용자를 초대하세요.**
+
+데이터에 사용자 참조(계정 소유자, 담당자 등)가 포함되어 있다면, 가져오기 전에 해당 사용자가 Twenty에 존재해야 합니다. 그렇지 않으면 해당 관계를 매핑할 수 없습니다.
+</Warning>
+
+1. **설정 → 구성원**으로 이동하세요.
+2. 모든 팀 구성원을 초대하세요
+3. **모두가 초대를 수락할 때까지 기다리세요**
+4. 모든 사용자가 구성원 목록에 표시되는지 확인하세요
+
+## 4단계: 현재 CRM에서 내보내기
+
+현재 CRM에서 데이터를 내보내세요:
+
+1. 보통 설정, 데이터 관리 또는 관리자 메뉴에 있는 **내보내기** 기능을 찾으세요
+2. 가능하면 **CSV 형식**으로 내보내세요
+3. 각 개체 유형을 별도로 내보내세요(회사, 연락처, 거래 등)
+4. 마이그레이션하려는 모든 필드를 포함하세요
+
+**다음 개체를 내보내세요(참고용 순서):**
+
+1. 회사 / 계정 / 조직
+2. 연락처 / 사람
+3. 거래 / 기회
+4. 노트 및 활동
+5. 사용자 지정 개체
+
+## 5단계: 데이터 정리 및 형식 지정
+
+내보낸 각 CSV를 스프레드시트 애플리케이션에서 열고 Twenty에 맞게 준비하세요.
+
+### 중복 제거
+
+1. 고유 필드(사람: 이메일, 회사: 도메인)로 정렬하세요
+2. 중복 행을 제거하거나 병합하세요
+3. Twenty에 이미 중복이 없는지 확인하세요
+
+### 필드 형식을 올바르게 지정
+
+| 필드 유형     | 필수 형식                       |
+| --------- | --------------------------- |
+| **도메인**   | `https://domain.com`        |
+| **이메일**   | `name@domain.com` (고유해야 함)  |
+| **날짜**    | `YYYY-MM-DD`                |
+| **전화**    | 세 개의 열: 번호, 국가 코드, 전화 걸기 코드 |
+| **부울**    | `TRUE` 또는 `FALSE` (대문자)     |
+| **선택 필드** | 표시 레이블이 아니라 API 이름을 사용하세요   |
+
+<Warning>
+**도메인 형식이 중요합니다.**
+
+`https://domain.com`을 사용하세요(`domain.com` 또는 `www.domain.com`은 사용하지 마세요). 이는 Twenty의 형식과 일치하며 이메일/캘린더 동기화를 연결할 때 중복을 방지합니다.
+</Warning>
+
+모든 필드 유형에 대한 전체 형식 요구 사항은 [CSV 파일 준비 방법](/l/ko/user-guide/data-migration/how-tos/prepare-your-csv-files)을 참조하세요.
+
+### 관계 열 추가
+
+레코드를 연결하려면(예: 사람을 회사에) 상위 레코드의 고유 식별자가 있는 열을 추가하세요.
+
+**예: 회사 링크가 포함된 사람 CSV**
+
+```csv
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+레코드 연결에 대한 자세한 지침은 [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)을 참조하세요.
+
+### 사용자 참조 업데이트
+
+데이터에 사용자 할당(소유자, 담당자)이 포함된 경우:
+
+1. **사용자의 이메일**이 포함된 열을 추가하세요(이전 시스템의 ID만이 아니라)
+2. 사용자가 Twenty 워크스페이스에 참여할 때 사용한 것과 동일한 이메일 주소를 사용하세요
+
+전체 형식 가이드는 [CSV 파일 준비 방법](/l/ko/user-guide/data-migration/how-tos/prepare-your-csv-files)을 참조하세요.
+
+## 6단계: Twenty로 가져오기
+
+<Warning>
+**가져오기 순서가 중요합니다!**
+
+항상 다음 순서로 가져오세요:
+1. **회사** 먼저(종속성 없음)
+2. 그다음 **사람**(회사에 연결)
+3. **기회** 세 번째(회사/사람에 연결)
+4. **노트와 작업**(레코드에 연결)
+5. **사용자 지정 객체**(종속성에 따름)
+
+참조하려면 상위 레코드가 먼저 존재해야 합니다.
+</Warning>
+
+### 각 객체 가져오기
+
+각 CSV 파일에 대해 다음 순서로 진행하세요:
+
+1. Twenty에서 해당 객체로 이동하세요
+2. **⋮ → 레코드 가져오기**를 클릭하세요
+3. CSV 파일을 업로드하세요
+4. 열을 필드에 매핑하세요:
+   * 사용자 이메일 열을 해당 관계 필드에 매핑하세요
+   * 관계 열(예: `companyDomain`)을 관계 필드에 매핑하세요
+5. UI에서 오류를 검토하고 수정하세요
+6. 가져오기를 확인하세요
+7. 다음 파일로 진행하기 전에 몇 개의 레코드를 확인하세요
+
+**상세 가이드:**
+
+* [회사 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-companies-via-csv)
+* [연락처 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-contacts-via-csv)
+* [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)
+
+## 7단계: 대규모 마이그레이션(레코드 50,000개 이상)
+
+대규모 마이그레이션의 경우:
+
+| 규모                   | 권장 방법         |
+| -------------------- | ------------- |
+| 10,000개 미만의 레코드      | 단일 CSV 가져오기   |
+| 10,000 - 50,000개 레코드 | 여러 CSV 파일로 분할 |
+| 50,000개 이상의 레코드      | API 사용        |
+
+**API 가져오기의 경우:**
+
+* 대규모 데이터 세트에 대해 더 빠르고 신뢰성이 높음
+* 배치 작업 지원(호출당 최대 60개 레코드)
+* 자세한 내용은 [API로 데이터 가져오는 방법](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)을 참조하세요
+
+## 8단계: 마이그레이션 이후 설정
+
+데이터를 가져온 후 워크스페이스 구성을 완료하세요:
+
+### 뷰 다시 만들기
+
+* 필터, 정렬, 열 구성이 포함된 저장된 뷰를 설정하세요
+* 필요한 칸반 또는 캘린더 뷰를 만드세요
+
+### 워크플로우 재구성
+
+* 자동화를 **설정 → 워크플로우**에서 다시 만드세요
+* 가장 중요한 워크플로우부터 시작하세요
+* 사용하기 전에 각 워크플로우를 테스트하세요
+
+### 역할 및 권한 구성
+
+* **설정 → 구성원 → 역할**에서 역할을 설정하세요
+* 적절한 역할에 사용자를 할당하세요
+
+### 이메일 및 캘린더 연결
+
+* 각 사용자는 **설정 → 계정**에서 자신의 계정을 연결합니다
+* Twenty가 이메일을 연락처 레코드와 동기화하기 시작합니다
+* 자세한 내용은 [이메일 및 캘린더](/l/ko/user-guide/calendar-emails/overview)를 참조하세요
+
+### 팀 교육
+
+* 함께 새 인터페이스를 살펴보세요
+* 팀별 프로세스를 문서화하세요
+
+## 일반적인 문제와 해결책
+
+| 문제               | 원인                 | 해결책                                         |
+| ---------------- | ------------------ | ------------------------------------------- |
+| **중복 오류**        | 이메일/도메인이 이미 존재함    | 파일에서 중복을 제거하거나 고유 식별자를 포함하여 기존 레코드를 업데이트하세요 |
+| **관계를 찾을 수 없음**  | 상위 레코드가 존재하지 않음    | 상위 객체를 먼저 가져오세요(회사를 사람보다 먼저)                |
+| **누락된 필드**       | 사용자 지정 필드가 존재하지 않음 | 가져오기 전에 설정 → 데이터 모델에서 필드를 생성하세요             |
+| **선택 필드 오류**     | 표시 레이블 사용 중        | API 이름을 사용하세요(설정에서 고급 모드를 활성화하여 찾을 수 있음)    |
+| **사용자 관계 비어 있음** | 사용자가 초대를 수락하지 않음   | 가져오기 전에 모든 사용자가 초대를 수락했는지 확인하세요             |
+
+자세한 문제 해결 단계는 [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)을 참조하세요.
+
+## 마이그레이션 후 체크리스트
+
+### 데이터 무결성
+
+<Check>모든 레코드가 가져와졌음(원본 시스템과 개수 비교)</Check>
+<Check>관계가 정상적으로 작동함(사람이 회사에 연결됨)</Check>
+<Check>사용자 할당이 올바르게 매핑됨(소유자, 담당자)</Check>
+<Check>사용자 지정 필드가 채워졌음</Check>
+<Check>예상치 못한 중복 없음</Check>
+
+### 구성
+
+<Check>뷰 재생성 완료</Check>
+<Check>워크플로우 재생성 및 테스트 완료</Check>
+<Check>역할 및 권한 구성 완료</Check>
+<Check>이메일/캘린더 동기화 연동 완료</Check>
+
+### 팀 준비 상태
+
+<Check>새 시스템에 대한 팀 교육 완료</Check>
+<Check>기존 CRM 접근 계획 결정(참고용으로 유지? 언제 비활성화할지?)</Check>
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="워크플로우를 자동으로 마이그레이션할 수 있나요?">
+    현재는 불가능합니다. 워크플로우는 Twenty에서 수동으로 다시 만들어야 합니다.
+  </Accordion>
+
+  <Accordion title="파일 첨부는 어떻게 하나요?">
+    파일 첨부는 CSV 내보내기에 포함되지 않습니다. 수동으로 다시 업로드하거나 API를 통해 마이그레이션하거나 지원이 필요하면 당사 팀에 문의하세요.
+  </Accordion>
+
+  <Accordion title="마이그레이션 중에 두 시스템을 모두 실행 상태로 유지할 수 있나요?">
+    예, 마이그레이션이 완료되었음을 확인할 때까지 기존 CRM을 실행 상태로 유지할 것을 권장합니다. 다만 두 곳 모두에서 새 데이터를 생성하지 않도록 주의하세요.
+  </Accordion>
+
+  <Accordion title="마이그레이션에는 일반적으로 얼마나 걸리나요?">
+    데이터의 규모와 복잡도에 따라 다릅니다. 소규모 마이그레이션(레코드 10,000개 미만)은 몇 시간 내에 완료할 수 있습니다. 대규모 마이그레이션은 데이터 정리와 테스트를 포함하여 며칠이 걸릴 수 있습니다.
+  </Accordion>
+</AccordionGroup>
+
+## 도움이 필요하신가요?
+
+<Tip>
+  마이그레이션에 도움이 필요하신가요? 데이터, 파이프라인, 사용자까지 엔드 투 엔드로 이전해 줄 [공인 Twenty 파트너를 찾아보세요](https://twenty.com/partners/list?categories=SOLUTIONING\&ref=docs-migrate-crm).
+</Tip>

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/migrating-from-self-hosted-to-cloud.mdx

@@ -0,0 +1,173 @@
+---
+title: 자가 호스팅에서 클라우드로 마이그레이션
+description: Twenty 자가 호스팅 인스턴스를 Twenty Cloud로 마이그레이션하는 단계별 가이드.
+---
+
+## 개요
+
+이 가이드는 Twenty 자가 호스팅 인스턴스에서 Twenty Cloud로 데이터를 마이그레이션하는 과정을 안내합니다. 이 프로세스에는 클라우드 워크스페이스 설정, 데이터 내보내기, 그리고 다시 가져오기가 포함됩니다.
+
+<Note>마이그레이션 후에는 뷰, 워크플로우, 역할을 수동으로 다시 만들어야 합니다. 이 구성 작업에 필요한 시간을 계획하세요.</Note>
+
+## 1단계: 클라우드 워크스페이스 생성
+
+1. [app.twenty.com](https://app.twenty.com)으로 이동하여 새 워크스페이스를 생성하세요
+2. 초기 설정 마법사를 완료하세요
+3. 새 워크스페이스 URL을 기록해 두세요
+
+## 2단계: 데이터 모델 다시 생성
+
+데이터를 가져오기 전에 사용자 지정 객체와 필드를 다시 만드세요:
+
+1. 클라우드 인스턴스에서 **설정 → 데이터 모델**로 이동하세요
+2. 자가 호스팅 설정과 일치하는 사용자 지정 객체를 생성하세요
+3. 표준 객체와 사용자 지정 객체에 사용자 지정 필드를 추가하세요
+4. 필드 설정(고유, 필수 등)을 구성하세요
+
+<Note>참고용으로 자가 호스팅 데이터 모델의 스크린샷을 찍거나, 두 인스턴스를 나란히 열어 두세요.</Note>
+
+## 3단계: 모든 사용자 초대
+
+<Warning>
+**중요: 데이터를 가져오기 전에 사용자를 초대하세요.**
+
+사용자가 참조되는 레코드(예: Account Owner 필드)를 가져오기 전에 초대를 수락해야 합니다. 사용자가 아직 존재하지 않으면 해당 관계를 매핑할 수 없습니다.
+</Warning>
+
+1. 클라우드 인스턴스에서 **설정 → 멤버**로 이동하세요
+2. 자가 호스팅에서 계정을 보유했던 모든 팀 멤버를 초대하세요
+3. **모두가 초대를 수락할 때까지 기다리세요**
+4. 모든 사용자가 멤버 목록에 표시되는지 확인하세요
+
+## 4단계: 자가 호스팅에서 데이터 내보내기
+
+자가 호스팅 인스턴스에서 각 객체를 내보내세요:
+
+1. 각 객체(회사, 사람, 기회 등)로 이동하세요
+2. 마이그레이션하려는 **모든 열**이 보이도록 뷰를 구성하세요
+3. **⋮ → 뷰 내보내기**를 클릭하세요
+4. 각 CSV 파일을 명확한 이름으로 저장하세요(예: `companies-export.csv`)
+
+**다음 순서로 내보내세요**(가져올 때 참고용):
+
+1. 회사
+2. 사람들
+3. 기회
+4. 사용자 지정 객체(종속성을 따름)
+5. 작업, 노트
+
+## 5단계: 워크스페이스 멤버 참조 업데이트
+
+내보낸 CSV에는 자가 호스팅 인스턴스의 사용자 ID가 포함되어 있습니다. 이 ID는 클라우드 인스턴스와 일치하지 않으므로 이메일로 대체해야 합니다.
+
+**사용자 참조(Owner, Assignee 등)가 있는 각 CSV 파일의 경우:**
+
+1. 스프레드시트 애플리케이션에서 CSV를 여세요
+2. 각 사용자 ID 열 옆에 새 열을 추가하세요(예: `accountOwnerId` 옆에 `accountOwnerEmail`)
+3. 각 사용자의 **이메일 주소**를 입력하세요
+4. 이전 ID 열은 삭제하거나 그대로 둘 수 있습니다(가져오기 중에 건너뜁니다)
+
+**예시:**
+
+이전:
+
+```csv
+name,domain,accountOwnerId
+Acme Corp,https://acme.com,old-uuid-123
+```
+
+이후:
+
+```csv
+name,domain,accountOwnerEmail
+Acme Corp,https://acme.com,john@yourcompany.com
+```
+
+<Note>사용자가 클라우드 워크스페이스 초대를 수락할 때 사용한 것과 동일한 이메일 주소를 사용하세요.</Note>
+
+## 6단계: 가져오기 순서 계획
+
+관계를 유지하려면 올바른 순서로 파일을 가져오세요:
+
+1. 먼저 **회사**(종속성 없음)
+2. 그다음 **사람**(회사에 연결)
+3. 세 번째로 **기회**(회사 및 사람에 연결)
+4. **사용자 지정 객체**(종속성을 따름)
+5. 마지막으로 **작업과 노트**(다른 레코드에 연결)
+
+관계 유지에 대한 자세한 내용은 [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)을 참조하세요.
+
+## 7단계: 클라우드로 가져오기
+
+각 CSV 파일에 대해 다음 순서로 진행하세요:
+
+1. 클라우드 인스턴스에서 해당 객체로 이동하세요
+2. **⋮ → 레코드 가져오기**를 클릭하세요
+3. CSV 파일을 업로드하세요
+4. 열을 필드에 매핑하세요:
+   * 사용자 이메일 열을 해당 관계 필드에 매핑하세요
+   * 다른 열도 일반적으로 매핑하세요
+5. 오류가 있으면 검토하고 수정하세요
+6. 가져오기를 확인하세요
+7. 다음 파일로 진행하기 전에 몇 개의 레코드를 확인하세요
+
+## 8단계: 구성 다시 생성
+
+데이터를 가져온 후 다음을 수동으로 다시 만드세요:
+
+### 보기
+
+* 필터, 정렬, 열 구성과 함께 저장된 뷰를 다시 만드세요
+* 칸반 또는 캘린더 뷰를 설정하세요
+
+### 워크플로우
+
+* **설정 → 워크플로우**에서 자동화를 다시 만드세요
+* 사용하기 전에 각 워크플로우를 테스트하세요
+
+### 역할 및 권한
+
+* **설정 → 구성원 → 역할**에서 역할을 설정하세요
+* 적절한 역할에 사용자를 할당하세요
+
+### 통합
+
+* 각 사용자의 이메일 및 캘린더 동기화를 다시 연결하세요
+* 새 API 키로 모든 API 통합을 다시 구성하세요
+
+## 마이그레이션 후 체크리스트
+
+<Check>모든 데이터가 성공적으로 가져와졌음</Check>
+<Check>객체 간 관계가 올바르게 동작함</Check>
+<Check>사용자 할당(Owner, Assignee)이 올바르게 매핑됨</Check>
+<Check>뷰 재생성 완료</Check>
+<Check>워크플로우 재생성 및 테스트 완료</Check>
+<Check>역할 및 권한 구성 완료</Check>
+<Check>이메일/캘린더 동기화 재연결 완료</Check>
+<Check>API 통합이 새 키로 업데이트됨</Check>
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="워크플로우를 자동으로 마이그레이션할 수 있나요?">
+    현재는 불가능합니다. 워크플로우는 클라우드 인스턴스에서 수동으로 다시 만들어야 합니다.
+  </Accordion>
+
+  <Accordion title="파일 첨부 및 이미지는 어떻게 하나요?">
+    파일 첨부는 CSV 내보내기에 포함되지 않습니다. 첨부 파일은 수동으로 다시 업로드하거나 API를 통해 마이그레이션해야 하며, 대규모 마이그레이션의 경우 당사 팀에 연락하여 지원을 받으세요.
+  </Accordion>
+
+  <Accordion title="마이그레이션 중에 두 인스턴스를 모두 실행 상태로 유지할 수 있나요?">
+    예. 클라우드 마이그레이션이 완료되었음을 확인할 때까지 자가 호스팅 인스턴스를 실행 상태로 유지하는 것을 권장합니다. 단, 두 곳 모두에서 새 데이터를 생성하지 않도록 주의하세요.
+  </Accordion>
+
+  <Accordion title="사용자가 아직 초대를 수락하지 않았다면 어떻게 하나요?">
+    해당 사용자를 참조하는 레코드는 가져오기에 실패하거나 관계가 비어 있게 됩니다. 데이터를 가져오기 전에 모든 사용자가 초대를 수락했는지 확인하세요.
+  </Accordion>
+</AccordionGroup>
+
+## 도움이 필요하신가요?
+
+<Tip>
+  대규모 또는 복잡한 워크스페이스를 마이그레이션하고 있나요? 전체 마이그레이션을 처리할 [공인 Twenty 파트너](https://twenty.com/partners/list?categories=HOSTING\&ref=docs-migrate-cloud)를 찾아보세요. *(또는 저희 팀을 참조에 추가하세요: [contact@twenty.com](mailto:contact@twenty.com).)*
+</Tip>

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/prepare-your-csv-files.mdx

@@ -0,0 +1,267 @@
+---
+title: CSV 파일 준비
+description: Twenty로 가져오기 위한 데이터 형식 지정 단계별 가이드.
+---
+
+## 개요
+
+이 가이드는 성공적인 가져오기를 위해 CSV 파일을 준비하는 과정을 안내합니다. 오류를 피하려면 다음 단계를 따르세요.
+
+## 1단계: 파일 요구 사항 확인
+
+시작하기 전에 파일이 다음 요구 사항을 충족하는지 확인하세요:
+
+| 요구 사항     | 세부정보             |
+| --------- | ---------------- |
+| **형식**    | CSV, XLSX 또는 XLS |
+| **크기 제한** | 파일당 10,000 레코드   |
+| **인코딩**   | UTF-8 권장         |
+| **구조**    | 파일당 한 가지 오브젝트 유형 |
+
+<Note>10,000 레코드를 초과하는 데이터세트의 경우, 여러 파일로 분할하거나 [API 가져오기](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)를 사용하세요.</Note>
+
+## 2단계: 샘플 파일 다운로드
+
+**가장 중요한 단계입니다.** 샘플 파일은 Twenty가 기대하는 정확한 열 이름과 형식을 보여줍니다.
+
+1. 오브젝트 보기(사람들, 회사 등)로 이동하세요.
+2. **⋮** → **레코드 가져오기**를 클릭하세요
+3. **샘플 파일 다운로드**를 클릭하세요
+4. 이 파일을 템플릿으로 사용하세요
+
+<Note>**전문가 팁:** 대신 기존 레코드 몇 개를 내보내세요. 이렇게 하면 데이터가 어떻게 형식화되어야 하는지 실제 예를 얻을 수 있으며, 가져오는 동안 열 이름이 자동으로 매핑됩니다.</Note>
+
+## 3단계: 중복 값 제거
+
+Twenty는 일부 필드에 대해 고유성을 적용합니다. 중복 항목은 가져오기 오류를 유발합니다.
+
+| 객체            | 고유 필드                   |
+| ------------- | ----------------------- |
+| **사람들**       | `id`, `email`           |
+| **회사**        | `id`, `domain`          |
+| **사용자 지정 개체** | `id`, 그리고 고유로 표시한 모든 필드 |
+
+**가져오기 전에:**
+
+1. 스프레드시트를 고유 필드(이메일 또는 도메인)로 정렬하세요
+2. 중복 행을 제거하거나 병합하세요
+3. Twenty에 이미 존재하는 중복 항목이 있는지 확인하세요
+
+<Warning>**소프트 삭제된 레코드는 고유성에 포함됩니다.** Command Menu → 삭제된 레코드 보기에 있는 레코드는 중복 오류를 일으킵니다. 영구적으로 삭제하거나 복원한 후 업데이트하세요.</Warning>
+
+## 4단계: 각 필드 유형을 올바르게 형식 지정하기
+
+필드 유형에 따라 요구되는 형식이 다릅니다. 전체 참고 자료는 다음과 같습니다:
+
+### 텍스트 필드
+
+* 특별한 형식 지정이 필요 없습니다
+* 앞/뒤 공백은 자동으로 제거됩니다
+
+### 이메일 필드
+
+* 유효한 이메일 형식이어야 합니다: `name@domain.com`
+* 고유해야 합니다(파일 또는 Twenty에 중복이 없어야 함)
+* 추가 이메일의 경우 **Emails / Additional Emails** 열에서 다음 형식을 사용하세요:
+
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### 도메인 필드
+
+* **권장 형식**: `https://domain.com`
+* 이는 메일박스/캘린더 동기화에서 사용하는 형식과 일치하며 중복을 방지합니다
+* 두 열을 모두 채우세요:
+  * **Domain / Domain Label**: `domain.com`
+  * **Domain / Domain URL**: `https://domain.com`
+* 파일 내 및 Twenty에서 고유해야 합니다
+
+### 전화번호 필드
+
+전화번호는 여러 열이 필요한 **중첩 필드**입니다:
+
+| 열                                       | 예시           |
+| --------------------------------------- | ------------ |
+| **Phones / Primary Phone Number**       | `4159095555` |
+| **Phones / Primary Phone Country Code** | `US`         |
+| **Phones / Primary Phone Calling Code** | `+1`         |
+
+### 주소 필드
+
+Address는 여러 열로 구성된 **중첩 필드**이며(일부는 비워 둘 수 있음):
+
+* **Address / Address 1**: 주소 1행
+* **Address / Address 2**: 주소 2행(선택 사항)
+* **Address / City**: 도시 이름
+* **Address / State**: 주 또는 도
+* **Address / Country**: 국가 이름
+* **Address / Post Code**: 우편번호/ZIP 코드
+
+### 날짜 필드
+
+파일 전체에서 일관된 형식을 사용하세요:
+
+* `YYYY-MM-DD` (권장): `2024-03-15`
+* ISO 8601: `2024-03-15T10:30:00Z`
+
+### 숫자 필드
+
+* 숫자만 사용(텍스트 금지)
+* 소수점 구분 기호로 점(.)을 사용: `1234.56`
+* 천 단위 구분 기호 사용 금지(`1,234.56`는 사용하지 마세요)
+
+### 통화 필드
+
+통화는 두 개의 열이 필요한 **중첩 필드**이며, **두 열 모두** 채워야 합니다:
+
+| 열                     | 예시        |
+| --------------------- | --------- |
+| **Amount / Amount**   | `1234.56` |
+| **Amount / Currency** | `USD`     |
+
+### 부울 필드
+
+대문자 사용: `TRUE` 또는 `FALSE`
+
+<Warning>소문자 `true` 또는 `false`는 동작하지 않습니다.</Warning>
+
+### 선택 필드
+
+표시 라벨이 아니라 옵션의 **API 이름**을 사용하세요.
+
+**API 이름을 찾는 방법:**
+
+1. **설정 → 데이터 모델**로 이동
+2. 객체와 필드를 선택하세요
+3. **고급 모드**를 활성화하세요(오른쪽 하단 토글)
+4. API 이름을 복사하세요(예: `OPTION_1`, "Option 1" 아님)
+
+<Note>새 선택 옵션은 자동으로 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가하세요.</Note>
+
+### 다중 선택 필드
+
+배열 형식으로 API 이름을 사용:
+
+```
+["VALUE1","VALUE2"]
+```
+
+### 배열 필드
+
+JSON 배열 형식 사용:
+
+```
+["value1","value2"]
+```
+
+### 평점 필드
+
+다음 형식을 사용: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, 또는 `RATING_5`
+
+### 링크/URL 필드
+
+두 열을 모두 채우세요:
+
+* **Links / Link Label**: `Twenty`
+* **Links / Link URL**: `https://twenty.com`
+
+보조 링크의 경우 **Links / Secondary Links** 열을 사용하세요:
+
+```
+[{"url":"https://twenty.com","label":"Twenty"}]
+```
+
+### JSON 필드
+
+유효한 JSON 형식을 사용:
+
+```
+{"key":"value","key2":"value2"}
+```
+
+### ID 필드
+
+* **선택 사항**: 제공하지 않으면 Twenty가 ID를 자동 생성합니다
+* **형식**: UUID(예: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`)
+* **사용 사례**: 새로 생성하는 대신 기존 레코드를 업데이트하려면 ID를 포함하세요
+
+## 5단계: 관계 열 추가(레코드를 연결하는 경우)
+
+레코드를 다른 객체에 연결하려면(예: People을 Companies에) 관련 레코드의 고유 식별자가 있는 열을 추가하세요.
+
+**예시**: People을 Companies에 연결
+
+People CSV에 열을 추가:
+
+```
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+**관계에 대한 중요 규칙:**
+
+* 상위 레코드는 Twenty에 이미 존재해야 합니다
+* 라벨이 아니라 **도메인 URL** 형식(`https://domain.com`)을 사용하세요
+* 고유 식별자는 하나만 매핑하세요(`companyId`와 `companyDomain`을 모두 포함하지 마세요)
+* 워크스페이스 구성원은 이름이 아닌 **이메일**을 사용하세요
+
+<Warning>
+**가져오기 순서가 중요합니다!**
+
+"one" 측을 "many" 측보다 먼저 가져오세요:
+1. **회사** 먼저
+2. **연락처** 두 번째(회사 참조 포함)
+3. **기회** 세 번째
+
+참조하려면 상위 레코드가 먼저 존재해야 합니다.
+</Warning>
+
+자세한 지침은 [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)을 참조하세요.
+
+## 6단계: Twenty에 필드가 존재하는지 확인
+
+가져오기는 필드가 아니라 레코드를 생성합니다. 가져오려는 모든 필드는 데이터 모델에 이미 존재해야 합니다.
+
+**가져오기 전:**
+
+1. **설정 → 데이터 모델**로 이동
+2. 객체를 선택하세요
+3. 필요한 사용자 정의 필드를 생성하세요
+4. 필드 이름을 정확히 확인하세요(열 제목과 일치해야 합니다)
+
+## 7단계: 최종 체크리스트
+
+파일을 업로드하기 전에 다음을 확인하세요:
+
+<Check>파일 형식이 CSV, XLSX 또는 XLS이어야 합니다</Check>
+<Check>레코드 수가 10,000개 미만이어야 합니다</Check>
+<Check>인코딩이 UTF-8이어야 합니다</Check>
+<Check>이메일(연락처) 또는 도메인(회사)에 중복이 없어야 합니다</Check>
+<Check>날짜 형식이 전체에서 일관되어야 합니다</Check>
+<Check>도메인은 `https://domain.com` 형식을 사용해야 합니다</Check>
+<Check>부울 필드는 `TRUE` 또는 `FALSE`(대문자)를 사용해야 합니다</Check>
+<Check>선택 필드는 표시 라벨이 아닌 API 이름을 사용해야 합니다</Check>
+<Check>모든 사용자 정의 필드가 설정 → 데이터 모델에 존재해야 합니다</Check>
+<Check>상위 레코드를 하위 레코드보다 먼저 가져와야 합니다</Check>
+<Check>관계 열이 기존 레코드를 참조해야 합니다</Check>
+
+## 피해야 할 일반적인 실수
+
+| 실수                   | 해결책                                 |
+| -------------------- | ----------------------------------- |
+| `TRUE` 대신 `true` 사용  | 부울 값은 대문자여야 합니다                     |
+| 선택 필드에서 표시 라벨 사용     | 설정에서 API 이름을 찾아 사용하세요               |
+| 회사보다 연락처를 먼저 가져오기    | 항상 상위 객체를 먼저 가져오세요                  |
+| 통화 필드에 통화 코드 누락      | Amount와 Currency 열을 모두 채우세요         |
+| 잘못된 도메인 형식           | `https://domain.com` 형식을 일관되게 사용하세요 |
+| 관계에 여러 개의 고유 필드를 매핑함 | 하나만 매핑하세요(도메인 또는 ID, 둘 다는 안 됨)      |
+
+## 다음 단계
+
+파일이 준비되었습니다! 이제:
+
+* [회사 가져오기](/l/ko/user-guide/data-migration/how-tos/import-companies-via-csv) (먼저 가져오세요)
+* [연락처 가져오기](/l/ko/user-guide/data-migration/how-tos/import-contacts-via-csv)
+* [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)

packages/twenty-docs/l/ko/user-guide/data-migration/how-tos/update-existing-records-via-import.mdx

@@ -0,0 +1,198 @@
+---
+title: 가져오기로 기존 레코드를 업데이트
+description: CSV 가져오기를 사용해 레코드를 일괄 업데이트하는 완전한 단계별 가이드.
+---
+
+## 개요
+
+여러 레코드를 한 번에 업데이트해야 하나요? 하나씩 편집하는 대신 CSV 가져오기를 사용해 기존 레코드를 일괄 업데이트하세요.
+
+**사용 사례:**
+
+* 여러 사람의 직함 업데이트
+* 회사 정보를 일괄 변경
+* 새 사용자 지정 필드에 데이터 추가
+* 여러 레코드의 데이터 오류 수정
+
+## 작동 방식
+
+기존 레코드와 일치하는 **고유 식별자**가 포함된 파일을 가져오면, Twenty는 중복을 생성하는 대신 해당 레코드를 업데이트합니다.
+
+| 고유 식별자가...       | Twenty가...                 |
+| ---------------- | -------------------------- |
+| 기존 레코드와 일치함      | **업데이트** 기존 레코드            |
+| 어떤 레코드와도 일치하지 않음 | **생성** 새 레코드               |
+| 파일에 없음           | **생성** 새 레코드(자동 생성된 ID 포함) |
+
+<Warning>
+**다중 선택 필드는 병합되지 않고 덮어써집니다.**
+
+레코드에 `Option A`와 `Option B`가 선택되어 있고 `["Option C"]`를 가져오면, 가져온 후 해당 레코드에는 `Option C`만 남습니다. 가져오면 이전 선택 항목이 모두 대체됩니다 — 기존 선택에 추가되지 않습니다.
+
+기존 값을 유지하려면 가져오기에 모두 포함하세요: `["Option A","Option B","Option C"]`
+</Warning>
+
+## 1단계: 현재 데이터 내보내기
+
+먼저, 업데이트하려는 레코드를 내보내세요:
+
+1. 해당 객체(사람, 회사 등)로 이동합니다.
+2. **필요한 열을 추가** — 업데이트하려는 필드를 표시하려면 **옵션 → 필드**를 클릭하세요
+3. **필요하다면 필터링** — 업데이트하려는 레코드만으로 범위를 좁히세요
+4. **⋮** → **뷰 내보내기**를 클릭
+5. CSV 파일을 저장하세요
+
+<Note>**먼저 내보내는 이유?** 내보낸 파일은 올바른 형식을 갖추고 고유 식별자를 포함하며, 가져오는 동안 자동으로 매핑됩니다.</Note>
+
+### 내보내지는 내용
+
+* 현재 보기에서 표시되는 모든 열
+* 레코드의 고유 식별자(`id`, `email`, `domain`)
+* 수정할 수 있는 현재 필드 값
+
+## 2단계: CSV 파일 편집
+
+내보낸 파일을 스프레드시트 애플리케이션(Excel, Google Sheets 등)에서 여세요:
+
+1. **고유 식별자 열을 유지** — `id`, `email`, `domain`을 삭제하지 마세요
+2. 변경하려는 열의 값을 **업데이트**하세요
+3. **업데이트할 필요가 없는 열은 제거하세요** (선택 사항이지만 더 깔끔합니다)
+4. **고유 식별자 값을 변경하지 마세요** — 그렇지 않으면 Twenty가 새 레코드를 생성합니다
+
+### 예시: 직함 업데이트
+
+**내보낸 파일:**
+
+```csv
+id,email,firstName,lastName,jobTitle
+550e8400-e29b-41d4-a716-446655440001,john@acme.com,John,Smith,Sales Rep
+550e8400-e29b-41d4-a716-446655440002,jane@acme.com,Jane,Doe,Sales Rep
+550e8400-e29b-41d4-a716-446655440003,bob@acme.com,Bob,Johnson,Sales Rep
+```
+
+**편집 후:**
+
+```csv
+id,email,firstName,lastName,jobTitle
+550e8400-e29b-41d4-a716-446655440001,john@acme.com,John,Smith,Account Executive
+550e8400-e29b-41d4-a716-446655440002,jane@acme.com,Jane,Doe,Senior Account Executive
+550e8400-e29b-41d4-a716-446655440003,bob@acme.com,Bob,Johnson,Account Executive
+```
+
+<Warning>
+**고유 식별자 값을 변경하지 마세요.**
+
+`john@acme.com`을 `john.smith@acme.com`으로 변경하면 Twenty는 기존 레코드를 업데이트하는 대신 새 레코드를 생성합니다.
+</Warning>
+
+## 3단계: 업데이트된 파일 가져오기
+
+1. 객체로 이동
+2. **⋮** → **레코드 가져오기**를 클릭
+3. 편집한 CSV 파일을 업로드하세요
+4. **고유 식별자가 매핑되었는지 확인** — `email`, `domain`, `id`가 올바르게 매핑되었는지 검증하세요
+5. 필드 매핑을 검토하세요
+6. 오류가 있는지 확인하세요
+7. **확인**을 클릭
+
+Twenty는 고유 식별자로 레코드를 매칭하여 새 값으로 업데이트합니다.
+
+## 적합한 고유 식별자 선택
+
+| 객체            | 권장        | 대안   | 노트                  |
+| ------------- | --------- | ---- | ------------------- |
+| **사람들**       | `이메일`     | `id` | 이메일은 사람이 읽기 쉬움      |
+| **회사**        | `도메인`     | `id` | 도메인은 사람이 읽기 쉬움      |
+| **사용자 지정 개체** | 임의의 고유 필드 | `id` | 사용자 지정 고유 필드를 사용하세요 |
+
+<Note>**하나의 고유 식별자만 사용하세요.** `email`과 `id`를 둘 다 매핑하지 마세요. 이로 인해 혼란과 오류가 발생할 수 있습니다.</Note>
+
+### 사용자 지정 고유 필드 사용
+
+고유로 표시된 사용자 지정 필드(다른 시스템의 외부 ID 등)가 있는 경우:
+
+1. 내보내기와 가져오기에 해당 필드를 포함하세요
+2. 가져올 때 해당 필드를 매핑하세요
+3. Twenty가 해당 필드로 매칭합니다
+
+## 4단계: 업데이트 확인
+
+가져온 후:
+
+1. 업데이트된 레코드 몇 개를 열어보세요
+2. 변경 사항이 적용되었는지 확인하세요
+3. 중복 레코드가 생성되지 않았는지 확인하세요
+
+## 파일에 없는 필드는 어떻게 되나요?
+
+**가져오기 파일에 포함되지 않은 필드는 변경되지 않습니다.**
+
+| 파일에 포함된 항목...                | 결과                                   |
+| ---------------------------- | ------------------------------------ |
+| `email`, `jobTitle`          | `jobTitle`만 업데이트되며, 다른 필드는 그대로 유지됩니다 |
+| `email`, `jobTitle`, `phone` | `jobTitle`과 `phone`이 업데이트됩니다         |
+
+즉, 변경하려는 필드(및 고유 식별자)만 포함하면 됩니다.
+
+## 업데이트와 새 레코드 조합
+
+하나의 가져오기에서 기존 레코드를 업데이트하고 새 레코드를 생성할 수 있습니다:
+
+```csv
+email,firstName,lastName,jobTitle
+john@acme.com,John,Smith,Senior Manager    ← Updates existing (email matches)
+newperson@acme.com,New,Person,Analyst      ← Creates new (email doesn't match)
+```
+
+## 피해야 할 일반적인 실수
+
+| 실수              | 문제                                                     | 결과                 | 해결책                               |
+| --------------- | ------------------------------------------------------ | ------------------ | --------------------------------- |
+| **고유 식별자 변경**   | `john@acme.com`을 `john.smith@acme.com`으로 변경함           | 업데이트 대신 새 레코드를 생성함 | 고유 식별자를 변경하지 마세요                  |
+| **여러 개의 고유 필드** | `email`과 `id`를 모두 매핑함                                  | 매칭 충돌 가능성          | 고유 식별자를 하나만 매핑하세요                 |
+| **고유 식별자 없음**   | 파일에 `firstName`, `lastName`, `jobTitle`만 있음            | 모든 행이 새 레코드를 생성함   | 항상 `email`, `domain`, `id`를 포함하세요 |
+| **대소문자 불일치**    | 파일에는 `John@acme.com`이 있지만 Twenty에는 `john@acme.com`이 있음 | 새 레코드 생성           | 정확한 값을 얻으려면 Twenty에서 내보내세요        |
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="일부 레코드가 아직 없으면 어떻게 하나요?">
+    고유 식별자가 기존 레코드와 일치하지 않는 레코드는 새 레코드로 생성됩니다. 이렇게 하면 하나의 가져오기에서 업데이트와 생성을 함께 수행할 수 있습니다.
+  </Accordion>
+
+  <Accordion title="필드 값을 비울 수 있나요?">
+    예, CSV에서 해당 셀을 비워두세요. 가져오면 기존 레코드의 해당 필드 값이 비워집니다.
+  </Accordion>
+
+  <Accordion title="가져오기에 포함하지 않은 필드는 어떻게 되나요?">
+    가져오기 파일에 없는 필드는 기존 레코드에서 변경되지 않습니다. 포함한 필드만 업데이트됩니다.
+  </Accordion>
+
+  <Accordion title="관계 필드(예: 회사)를 업데이트할 수 있나요?">
+    예! 관계의 고유 식별자(예: `companyDomain`)를 포함하고 관계 필드에 매핑하세요. 관계가 업데이트됩니다.
+  </Accordion>
+
+  <Accordion title="어떤 레코드는 업데이트되고 어떤 레코드는 생성되는지 어떻게 알 수 있나요?">
+    가져오기 검토 단계에서 Twenty가 고유 식별자 일치 여부를 기준으로 업데이트될 레코드와 생성될 레코드 수를 보여줍니다.
+  </Accordion>
+
+  <Accordion title="일괄 업데이트를 되돌릴 수 있나요?">
+    자동 실행 취소 기능은 없습니다. 대량 업데이트 전에 데이터를 백업용으로 내보내는 것을 권장합니다.
+  </Accordion>
+</AccordionGroup>
+
+## 모범 사례
+
+1. **먼저 내보내기** — 올바른 형식을 보장하려면 항상 내보내기에서 시작하세요
+2. **업데이트 전에 백업** — 대량 변경 전에 데이터를 내보내세요
+3. **일부 레코드로 테스트** — 대량 작업 전에 먼저 5~10개의 레코드를 업데이트해 보세요
+4. **사람이 읽기 쉬운 식별자 사용** — `email`과 `domain`이 `id`보다 확인하기 더 쉽습니다
+5. **필요한 열만 포함** — 열이 적을수록 오류 가능성이 줄어듭니다
+
+## 문제 해결
+
+문제가 있으신가요? 확인하세요:
+
+* [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)
+* [고유성 제약 조건](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)
+* [필드 매핑 레퍼런스](/l/ko/user-guide/data-migration/capabilities/field-mapping)