🧠Junghanacs

Recent Notes

#한국어 #기술문서 #스타일 #가이드

Jun 23, 202324 min read

:rule:style:writing:

한글 기술 문서 작성 방법을 정리해보자. 나의 관점에서.

관건은 무엇인가

[2023-07-18 Tue 16:08]

  • 한글 스타일 가이드 문서화 -- 목록화 해야 된다. 내가 전체를 알아야 건들 수가 있다
  • 일본 코드 재활용성 확보
  • 직접 개발 일본 코드 재활용하면서 익히고 나서

NOTE 한글 기술 문서 린터 스타일 학습 및 정리

일단 목표를 잡고 가야 할 듯. 다 개발 한다고 가정하고 그냥 하면 된다. 한글 가이드를 일단 다 공부해서 하나로 통합한다.

즉, 하나의 언어에 대한 확실한 기준이 있어야 일본 버전을 가져다 쓸지 말지 결정할 것이다.

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 에 나타나는 한글 글자는 퍼센트 인코딩 적용 없이 있는 그대로 씁니다. 근거

| 원문 | 번역문 | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | <b><a href"https://en.wikipedia.org/wiki/CMYK_color_model">CMYK (Cyan, Magenta, Yellow, Key)</a></b>, is the model used by printers and other ink- based media.= | <b><a href"https://ko.wikipedia.org/wiki/CMYK_%EA%B0%90%EC%82%B0%ED%98%BC%ED%95%A9">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 이 잘못되었습니다. |

두문자어를 설명할 때 풀어서 쓴 두문자어 다음에 두문자어가 나오거나 그 반대로 나올 수도 있습니다. 한국어로 번역할 때에는 그것과 상관 없이 두문자어를 먼저 쓴 다음 괄호 안에 두문자어의 풀이를 씁니다. (적용 예정)

한글 맞춤법

본래 이 문서에 한글 맞춤법의 내용을 그대로 붙여넣을 필요는 없지만, 상당히 많은 자유 소프트웨어 한국어 번역 프로젝트에서 한글 맞춤법을 지키지 않는 부분이 많아서 이 문서에서도 중요한 일부를 언급합니다.

준말과 본말은 둘 다 맞춤법에 맞는 말이지만, 준말과 본말 중 어느 쪽으로 통일해서 쓸 지는 개별 어간에 따라서 달라집니다. 대부분 어간은 줄여서 씁니다. 예를 들어 "하여"는 한 음절인 "해"로 줄여서 씁니다. 단 "되어"는 준말인 "돼"보다는 본말인 "되어" 쪽으로 씁니다. (제 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 설정 내보내기 |

제 3 자(third party)의 상표명을 언급한다면, 해당 제 3 자가 공식적으로 한국어 음차 표기를 하거나 한국어 상표명을 사용하는 경우에만 상표명을 번역합니다.

| 원문 | 번역문에 사용할 상표명 | |---------------|--------------| | GNOME | 그놈 | | Twitter | 트위터 | | Facebook | Facebook | | Google Calendar | Google 캘린더 | | Firefox | Firefox |

번역 메시지 내에 등장하는 사람의 이름은 읽는 방법이 알려지지 않았다면 원어 그대로 표기합니다. 인명의 음차는 본인에게 물어보지 않는 한 정확한 방법을 알기 어려우며, 같은 글자로 써 놓은 이름이라고 하더라도 언어에 따라 읽는 방법이 달라집니다. 일부 이름은 음차 표기를 하고 일부는 그렇지 않은 것을 방지하려고 모든 이름을 원어 그대로 표기합니다. 단 한국인의 이름은 한글로 표기합니다.

한글 참고 -- 카카오 기술 문서 관련

모든 문서 읽고 이를 하나로 통합한다.

NOTE 한국어 글쓰기 (전뇌해커님)

[2023-06-26 Mon 17:06] https://github.com/ychoi-kr/ko-prfrdr/tree/main

이게 정말 엄청난 양의 내용을 담고 있는데 이걸 어떻게 내가 활용하도록 할 수 있나?!

Linter .... 실시간으로 뭘 테크니컬 다 검사할 것 아니다. 실시간으로 못한다.

5 한국어 - IT 글쓰기와 번역 노트 많은 내용을 다루고 있다.

인공지능을 활용한 테스트 결과 :: 대단하시네 언제 이걸 다 문장 교정 - 생성 AI 활용기: ChatGPT, OpenAI API, Stable Diffusion

글첵 : 전문가용 문장 검사기

[2023-11-08 Wed 15:15]

이게 전뇌해커님의 Linter 온라인 버전.

글첵 - 전문가용 문장 검사기 - geulcheck.pythonanywhere.com

‘글첵’은 IT 전문 출판 편집자가 직접 개발한 맞춤법/문장 검사기이며, 누구나 무료로 사용할 수 있습니다. 교정할 문장을 입력하고 검사해 보세요.
 
------------------------------
 
석조보살입상은 비마라사 근처 밭에 흩어져 있던 것을 수습한 것이다.  부처상과 받침이 같은 돌로 되어 있으며 형태는 서있는 형태인 입상(立像)이다. 발굴 당시에는 목과 허리 부분이 절단된 것을 다시 붙여놓았다.
불상의 전체높이 151cm, 머리 높이 27cm, 어깨너비 34cm, 받침돌 높이 14cm, 받침돌 직경 54cm, 가슴너비 23cm이다. 왼손은 가슴에 대고 오른손은 옆으로 내려 천의자락을 잡고 있는 형상인데, 불신(佛身)의 비례는 균형이 잡히고 몸의 굴곡이 부드럽게 드러나고 있다.
 
- 한눈에 알아보는 문화재 안내문 바로 쓰기, https://www.korean.go.kr/front/etcData/etcDataView.do?mn_id=46&etc_seq=495

NOTE [#A] 한글 기술 문서 스타일 표준안 초안

[2023-07-14 Fri 10:48] 참고 하여 정리하자. 막연하면 안되고 중요도 예시가 있어야 된다. 그래야 TDD 로 작업이 된다. 이는 다음에 코드로 가능한 부분들을 정리하면 된다.

NOTE 한국어 번역 파일 (PO) 검사 도구

[2023-07-18 Tue 16:05] https://github.com/changwoo/ko-po-check/

참고 문헌

https://community.kde.org/KDE_Localization/ko/styleguide

Related-Notes

References

Backlinks

  • No backlinks found