--- title: "#한글: #한국어 #기술문서 #스타일 #가이드 #테크니컬라이터 #글쓰기" url: "https://notes.junghanacs.com/notes/20230623T170100" author: "Junghan Kim" date: "2023-06-23T17:01:00+09:00" lastmod: "2024-12-01T06:30:00+09:00" tags: ["guide","hangul","linter","rule","style","writing"] description: "한글 기술문서 스타일 가이드와 테크니컬 라이팅 기준을 정리해 린터 개발의 바탕으로 삼으려는 기록." --- > [!abstract] 이 노트에 대하여 > > 한글 기술문서 스타일 가이드와 테크니컬 라이팅 자료를 한데 모아 기준선을 세운다. 직접 규칙을 만들고 일본 쪽 자산을 재활용하기 위한 준비 단계의 문제의식이 담겨 있다. ## 히스토리 - [2025-06-08 Sun 11:57] 정리 - [2023-07-18 Tue 16:08] 기술 글쓰기 ## 2023 한글 기술 문서 작성의 현재 [2023-07-18 Tue 16:08] - 한글 스타일 가이드 문서화 -- 목록화 해야 된다. 내가 전체를 알아야 건들 수가 있다 - 일본 코드 재활용성 확보 - 직접 개발 일본 코드 재활용하면서 익히고 나서 - [#린터: #텍스트린트: JTF Japanese Rules](https://notes.junghanacs.com/notes/20230718T161700) - [#기술글쓰기 #연재 - #카카오](https://notes.junghanacs.com/notes/20230717T103600) 한글 기술 문서 작성 방법을 정리해보자. 나의 관점에서. ### 한글 기술 문서 린터 스타일 학습 및 정리 일단 목표를 잡고 가야 할 듯. 다 개발 한다고 가정하고 그냥 하면 된다. 한글 가이드를 일단 다 공부해서 하나로 통합한다. 즉, 하나의 언어에 대한 확실한 기준이 있어야 일본 버전을 가져다 쓸지 말지 결정할 것이다. KDE 번역물은 크게 GUI, 도움말, 웹 사이트 세 가지로 구성됩니다. 번역 문자열의 원본 언어는 항상 영어입니다. 영어 문장 구조의 1:1 직역을 지양하고 최대한 자연스러운 한국어 문장으로 번역하는 것을 목표로 합니다. 국어 규범집을 다 볼 수는 없다. 지켜야 할 것들 수준에서 정리한다. #### 전문 용어 사용 전문적인 느낌을 줄 수 있는 문장을 사용해야 합니다. 번역문을 읽는 사용자가 배경 지식이 충분하다고 간주할 수 있으면 전문 용어를 의미가 다른 "쉬운" 용어로 대체하지 않습니다. #### 하십시오 기본적인 문장은 하십시오체(합쇼체라고도 함)를 사용합니다. 해요체의 사용은 예외적인 곳에만 허용합니다. | 원문 | ✔ | ❌ | |--------------------------------|--------------------------------|------------------------------| | **restart** Kdenlive to apply | 적용하려면 Kdenlive 를 **다시 시작하십시오** | 적용하려면 Kdenlive 를 **다시 시작하세요** | | Really **delete** these entries? | 이 항목을 정말로 **삭제하시겠습니까?** | 이 항목을 정말로 **삭제할까요?** | #### 피동형 지양 문장에서의 피동형 사용을 지양합니다. 영어 원문이 수동형 문장이라고 하더라도, 한국어 번역에 굳이 피동형 문장을 사용할 이유는 없습니다. | 원문 | ✔ | ❌ | |----|-----|-----| | Do | 합니다 | 해집니다 | #### 구조 영어 문장 구조를 항상 1:1 로 번역하지 않습니다. 만약 한국어로 번역했을 때 부정적인 어감이 들거나, 한국어 화자가 이해하기 힘든 표현이 원문에 있었다면 해당 표현을 뉘앙스를 잃지 않은 상태에서 적절하게 바꿉니다. | 원문 | ✔ | ❌ | |----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------------------------------| | Meet friends on the net, make new acquaintances and **lose yourself** in talk about your favorite subject. | 인터넷에서 친구를 만나고, 새로운 지인을 사귀고, 좋아하는 주제에 대해 이야기하면서 **시간을 보낼 수 있습니다.** | 인터넷에서 친구를 만나고, 새로운 지인을 사귀고, 좋아하는 주제에 대해 이야기하면서 **자신을 잃어 버리십시오.** | URL 이 메시지에 등장할 때, 동등한 한국어 문서가 존재한다면 한국어 문서의 URL 로 대체합니다. 예: MDN, 위키백과. 자리 비움자와 혼동될 가능성이 있으므로 URL 에 나타나는 한글 글자는 퍼센트 인코딩 적용 없이 있는 그대로 씁니다. [근거](https://marc.info/?l=kde-i18n-doc&m=155828201626804&w=2) | 원문 | 번역문 | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `">CMYK (Cyan, Magenta, Yellow, Key)</a></b>, is the model used by printers and other ink- based media.= | `_ 감산혼합">CMYK(시안, 마젠타, 옐로, 키)</a></b>는 프린터 및 기타 잉크 기반 매체에서 사용하는 색 모델입니다.= | #### 마침표 - 문장 기준 원문이 마침표로 끝날 때에는 마침표까지 찍은 완전한 문장으로 번역하며, 마침표로 끝나지 않으면 완전한 문장으로 번역하지 않습니다. #### 높임법 문장 하나에 동사가 여러 개 있으면 맨 마지막 동사에만 높임법을 적용합니다. | 원문 | ✔ | ❌ | |-------------------------------------------------------------------|------------------------------------------|------------------------------------------| | **Click** this button **to save** the Java policy to a zipped file. | 자바 정책을 압축 파일로 **저장하려면** 이 단추를 **누르십시오.** | 자바 정책을 압축 파일로 **저장하시려면** 이 단추를 **누르십시오.** | #### 인칭 대명사 인칭 대명사, 특히 2 인칭 대명사는 가급적 사용하지 않습니다. 영어 원문에 'You'가 등장한다고 하더라도 한국어로 'You'를 그대로 옮기지 않습니다. | 원문 | ✔ | ❌ | |------------------------------------|--------------------|------------------------| | Connect KDE with **your** smartphone | **내** 스마트폰과 KDE 연결 | **당신의** 스마트 폰과 KDE 를 연결 | | What do **you** want to do now? | 무엇을 하시겠습니까? | **당신은 지금** 무엇을 하시겠습니까? | #### 문장 부호 한국어 문장 부호에는 쌍반점(;)이 없으며, 쉼표(,)도 영어에 비하면 적게 사용합니다. 원문에 있는 쌍반점은 의미가 전달될 수 있도록 다른 접속사 등을 사용하여 번역하고, 원문에 쉼표가 있다고 하더라도 한국어 문장에서 쉼표가 없는 게 더 자연스러운 경우에는 쉼표를 생략합니다. #### 단어 선택 **KDE 는 국어 순화 운동의 실험실이 아닙니다.** 이미 정착된 순화 용어를 받아들이는 것은 허용하나, KDE 가 앞장서서 순화 용어를 만들거나 보급할 이유는 없습니다. | 원문 | ✔ | ❌ | |-------|-------------|----| | Comment | 댓글(글에 대한) | 코멘트 | | Bug | 버그(프로그램) | 벌레 | | Desktop | 데스크톱, 바탕 화면 | 일터 | | Local | 로컬, 지역 | 울 안 | 더 나은 한자어나 고유어가 있고 해당 용어가 더 자주 사용된다면 외국어의 음차를 사용하지 않습니다. | 원문 | ✔ | ❌ | |--------|----------------|-----| | Player | 재생기(음악, 동영상 등) | 플레이어 | | Document | 문서 | 도큐멘트 | | User | 사용자 | 유저 | | Device | 장치 | 디바이스 | 두 개의 단어가 짝을 이룰 때에는 가급적 고유어는 고유어끼리, 한자어는 한자어끼리 짝을 맞춥니다. | 원문 | ✔ | ❌ | |----------|----------|---------| | Row/Column | 줄/칸, 행/열 | 줄/열, 행/칸 | 단어의 복수형은 사용하지 않으며, 문장 구조상 더 자연스러운 경우나 복수임을 강조해야 하는 경우에만 사용합니다. #### 두문자어 원문에서 두문자어를 복수형으로 쓴다고 하더라도 한국어에서는 단수형으로 씁니다. | 원문 | ✔ | ❌ | |---------------------------------------------------|---------------------------------|---------------------------------| | has Status **LEDs** right | 오른쪽 상태 **LED** 있음 | 오른쪽 상태 **LEDs** 있음 | | KDE tool for opening **URLs** from the command line | 명령행에서 **URL 을** 열 때 사용하는 KDE 도구 | 명령행에서 **URLs 를** 열 때 사용하는 KDE 도구 | 원문에서 두문자어의 첫 글자만 대문자라고 하더라도 한국어에서는 모두 대문자로 씁니다. | 원문 | ✔ | ❌ | |-------------------------------|------------------------|-----------------------| | **Url** to import is malformed. | 가져올 **URL 이** 잘못되었습니다. | 가져올 **Url 이** 잘못되었습니다. | 두문자어를 설명할 때 풀어서 쓴 두문자어 다음에 두문자어가 나오거나 그 반대로 나올 수도 있습니다. 한국어로 번역할 때에는 그것과 상관 없이 두문자어를 먼저 쓴 다음 괄호 안에 두문자어의 풀이를 씁니다. (적용 예정) #### 한글 맞춤법 본래 이 문서에 한글 맞춤법의 내용을 그대로 붙여넣을 필요는 없지만, 상당히 많은 자유 소프트웨어 한국어 번역 프로젝트에서 한글 맞춤법을 지키지 않는 부분이 많아서 이 문서에서도 중요한 일부를 언급합니다. - [한국어 어문 규범](https://kornorms.korean.go.kr/m/m_regltn.do?#a753) - 한글 맞춤법 - 국립 국어원 준말과 본말은 둘 다 맞춤법에 맞는 말이지만, 준말과 본말 중 어느 쪽으로 통일해서 쓸 지는 개별 어간에 따라서 달라집니다. 대부분 어간은 줄여서 씁니다. 예를 들어 "하여"는 한 음절인 "해"로 줄여서 씁니다. 단 "되어"는 준말인 "돼"보다는 본말인 "되어" 쪽으로 씁니다. (제 4 장 제 5 절 제 34 항) | 원문 | ✔ | ❌ | |--------------------|----------------|----------------| | Failed to read data. | 데이터를 읽지 못했습니다. | 데이터를 읽지 못하였습니다. | 조사는 앞말이 한글로 썼든, 숫자든, 외국어든 붙여 씁니다. 괄호 뒤에 조사가 나온다면 괄호 안에 있는 내용이 없다고 가정하고 조사를 붙입니다. 그러나 괄호가 함수에 전달할 인자를 가리키는 등 괄호 안에 있는 내용을 생략하면 문장이 성립하지 않는 경우에는 괄호 안에 있는 내용에 맞추어 조사를 붙입니다. (제 5 장 제 1 절 제 41 항) | 원문 | ✔ | ❌ | |------------------------------------------------------------------------------|-------------------------------------------|------------------------------------------| | Run within **Konsole** | **Konsole 에서** 실행 | **Konsole 에서** 실행 | | **The report** you selected (bug %1) is already marked as duplicate of bug %2. | 선택한 **보고서(버그 %1)는** 버그 %2 의 중복으로 표시되었습니다. | 선택한 **보고서(버그 %1)은** 버그 %2 의 중복으로 표시되었습니다. | | **LEN("hello")** returns 5 | **LEN("hello")는** 5 를 반환함 | **LEN("hello")은** 5 를 반환함 | 자리 비움자 다음에 조사가 올 때에는 조사의 사용 가능한 변형을 모두 작성합니다. 예: 이(가), 은(는), 을(를), 와(과), (으)로, (이)면. 만약 자리 비움자의 내용에 한글이 올 확률이 높다면 Transcript 문법을 사용해서 자동 조사 처리를 추가할 수 있습니다. `|/|` 기호 앞에는 자리 비움자 내용이 한글이 아닐 때의 문자열, 해당 기호 뒤에는 자동 조사 처리 시의 문자열을 추가합니다. | 원문 | 번역문 | |-------------------------|--------------------| | Already subscribed to %1. | 이미 %1 을(를) 구독하고 있습니다. | | Open with %1 | %1(으)로 열기 | 단위 명사는 수 관형사를 한글로 쓸 때에는 띄어서 쓰며, 차수를 나타내는 관형사나 숫자 뒤에 쓸 때에는 붙여서 씁니다. (제 5 장 제 2 절 제 43 항) 예외: 단위를 한글로 쓰지 않았을 경우에는 숫자와 띄어서 씁니다. | 원문 | ✔ | ❌ | |----------|--------|-------------| | One year | 1 년 | 1 년 | | Page %1 | %1 쪽 | %1 쪽, %1 페이지 | | %1 Byte(s) | %1 바이트 | %1 바이트 | | %1 KiB | %1 KiB | %1KiB | 복합 명사가 등장할 때에는 해당 명사 사이의 모든 단어를 띄어서 쓰는 것을 원칙으로 하며, 붙여서 쓰는 것이 더 자주 사용되는 경우에 예외를 허용합니다. (제 5 장 제 4 절 제 50 항) | 원문 | ✔ | ❌ | |-------|-------|-----| | Toolbar | 도구 모음 | 도구모음 | | Preview | 미리 보기 | 미리보기 | | Archive | 압축 파일 | 압축파일 | 문장 부호의 명칭은 한글 맞춤법 부록을 따릅니다. 필요한 경우 괄호 안에 문장 부호를 병기할 수 있습니다. 단 semicolon(;)은 "쌍반점"으로 부릅니다. 쌍반점 그 자체를 언급해야 하거나, 쌍반점을 그대로 입력해야 하는 메시지를 번역해야 하는 것이 아니면 한국어 문장에는 쌍반점을 사용하지 않습니다. | 원문 | 번역문 | |-----------------------------------------------------------------------------------------------|-------------------------------------------------------| | Export data as **comma** separated values | **쉼표로** 구분한 값으로 데이터 내보내기 | | Adding **a dot** to the beginning of this folder's name will hide it from view. | 폴더 이름 맨 처음에 **마침표를** 추가하면 더 이상 표시되지 않습니다. | | This field contains the address of your computer and the port number, separated by a **colon**. | 이 필드에는 **쌍점(:)** 으로 구분된 이 컴퓨터의 주소와 디스플레이 번호가 들어 있습니다. | | Unclosed **quotation mark.** | **따옴표를** 닫지 않았습니다. | | A **semicolon**-separated list of mime types for which this tool should be available. | 이 도구를 활성화할 문서의 MIME 형식입니다. 형식 여러 개는 **쌍반점(;)** 으로 구분합니다. | 쌍점(:) 앞에 오는 단어는 **쌍점과 띄어 쓰지 않습니다.** (부록 6 항) | 원문 | ✔ | ❌ | |------------|--------|--------| | Recent file: | 최근 파일: | 최근 파일 : | | Genre: | 장르: | 장르 : | 여는 괄호 앞에서는 띄어 쓰지 않습니다. (부록 10 항) | 원문 | ✔ | ❌ | |---------------------------|----------------|----------------| | Name (Description) | 이름(설명) | 이름 (설명) | | Large (%1 pixels) | 크게(%1 픽셀) | 크게 (%1 픽셀) | | Fill with Pattern (Opacity) | 패턴으로 채우기(불투명도) | 패턴으로 채우기 (불투명도) | 특히 다음 외래어 표기를 주의합니다. | 원문 | ✔ | ❌ | |---------|------|-----| | Directory | 디렉터리 | 디렉토리 | #### 이름(상표명, 인명) KDE 프로젝트 내부에서 만드는 상표명은 원칙적으로 번역하지 않습니다. 단, 사용자가 직접 실행할 일이 많지 않은 프로그램이나 일반 명사 혹은 KDE+ 일반 명사로만 이뤄진 프로그램에서는 일반 명사 부분의 의역을 제한적으로 허용합니다. KDE 프로젝트의 브랜드 작명법은 역사적으로 K 가 들어가는 일반 명사를 사용했으며(예: Falkon, DigiKam), 해당 상표명의 K 를 살리면서 한글로 음차하는 것이 항상 가능하지는 않기 때문입니다. 예를 들어 Konsole 의 경우 "콘솔"로 음차하면 "ㅋ" 부분이 K 인지 C 인지를 알 수가 없습니다. 음차를 한다고 해도, 알파벳을 읽는 방법이 언어마다 서로 다르기 때문에 같은 프로그램이라고 하더라도 개발자 내지 읽는 사람의 모국어에 따라서 얼마든지 다르게 읽힐 수 있습니다. 불행히도 프로그램 이름을 어떻게 읽어야 하느냐에 대해서는 개발자에게 직접 물어보지 않는 한 어떻게 되는지 알 수 없습니다. 비록 KDE 프로젝트의 일부이지만 K 가 들어가지 않는 프로그램도 등장하고 있으나(예: Dolphin, Spectacle) 이들만 한글로 음차하는 것은 일관성을 깨트리기 때문에 번역하지 않음 원칙은 계속 유지합니다. | 원문 | 번역문에 사용할 상표명 | |---------------------|------------------------| | Konsole | Konsole | | Dolphin | Dolphin. "돌핀"으로 음차하지 않습니다. | | Kate | Kate. "케이트"나 "카테"로 음차하지 않습니다. | | Plasma | Plasma. "플라즈마"로 음차하지 않습니다. | | Okular | Okular. "오큘라"나 "오큘러"로 음차하지 않습니다. | | KMail | KMail. "K 메일"로 음차하지 않습니다. | | KDE Connect | KDE Connect | | Akonadi Console | Akonadi 콘솔 | | PIM Settings Exporter | PIM 설정 내보내기 | - 참조: [Brand Names - KDE HIG](https://hig.kde.org/style/writing/brandnames.html) 제 3 자(third party)의 상표명을 언급한다면, 해당 제 3 자가 공식적으로 한국어 음차 표기를 하거나 한국어 상표명을 사용하는 경우에만 상표명을 번역합니다. | 원문 | 번역문에 사용할 상표명 | |---------------|--------------| | GNOME | 그놈 | | Twitter | 트위터 | | Facebook | Facebook | | Google Calendar | Google 캘린더 | | Firefox | Firefox | 번역 메시지 내에 등장하는 사람의 이름은 읽는 방법이 알려지지 않았다면 원어 그대로 표기합니다. 인명의 음차는 본인에게 물어보지 않는 한 정확한 방법을 알기 어려우며, 같은 글자로 써 놓은 이름이라고 하더라도 언어에 따라 읽는 방법이 달라집니다. 일부 이름은 음차 표기를 하고 일부는 그렇지 않은 것을 방지하려고 모든 이름을 원어 그대로 표기합니다. 단 한국인의 이름은 한글로 표기합니다. #### 한글 참고 -- 카카오 기술 문서 관련 모든 문서 읽고 이를 하나로 통합한다. ### 한글 기술 문서 스타일 표준안 초안 [2023-07-14 Fri 10:48] 참고 하여 정리하자. 막연하면 안되고 중요도 예시가 있어야 된다. 그래야 TDD 로 작업이 된다. 이는 다음에 코드로 가능한 부분들을 정리하면 된다. ### 한국어 번역 파일 (PO) 검사 도구 [2023-07-18 Tue 16:05] ### 관련링크 - - [KDE Human Interface Guidelines](https://hig.kde.org/) - [마이크로소프트 한국어 스타일 가이드, 2019년 2월](http://download.microsoft.com/download/6/3/9/639fc431-8d7d-482d-b80e-ae4971dc5270/kor-kor-styleguide.pdf) - [StarSuite Korean Style Guide, 2003년 11월](https://docs.google.com/viewer?a=v&pid=sites&srcid=ZGVmYXVsdGRvbWFpbnxsaWJyZW9mZmljZWwxMG5rb3JlYW58Z3g6MmRlN2Y2MDZjY2QzY2Fm) - [Facebook, Korean Style Guide for Community, 2019년 12월](https://scontent-ber1-1.xx.fbcdn.net/v/t39.2365-6/84555730_226170191720418_8763857205297414144_n.pdf?_nc_cat=111&_nc_sid=ad8a9d&_nc_ohc=NgzhAvBakjMAX8pcxhI&_nc_ht=scontent-ber1-1.xx&oh=28cd9044f30e703eaae54decc09f0102&oe=5EB62F6C) - [Second Life 한글화 지침서 (Korean Styleguide for SecondLife)](http://wiki.secondlife.com/wiki/Korean_Style_Guide/ko) - [Mozilla, Style Guides Korean (ko)](https://github.com/mozillakr/styleguides/blob/ko/docs/ko/README.md) - [ko-po-check](https://github.com/changwoo/ko-po-check/) ## 관련메타 - [#라이팅허브 #쓰기통 #글쓰기](https://notes.junghanacs.com/meta/20240902T173233) - [#한글 #한국어 #우리말](https://notes.junghanacs.com/meta/20231227T162134) - [#린터 - #교열 #린팅 #문장 #오류 #검사](https://notes.junghanacs.com/meta/20240123T173354) ## BIBLIOGRAPHY