#한글: #한국어 #기술문서 #스타일 #가이드 #테크니컬라이터 #글쓰기

히스토리

[2025-06-08 Sun 11:57] 정리
[2023-07-18 Tue 16:08] 기술 글쓰기

2023 한글 기술 문서 작성의 현재

[2023-07-18 Tue 16:08]

한글 스타일 가이드 문서화 — 목록화 해야 된다. 내가 전체를 알아야 건들 수가 있다
일본 코드 재활용성 확보
직접 개발 일본 코드 재활용하면서 익히고 나서
#린터: #텍스트린트: JTF Japanese Rules
#기술글쓰기 #연재 - #카카오

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

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

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

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

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_%C2%A0%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 설정 내보내기

참조: Brand Names - KDE HIG

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

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

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

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

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

한글 기술 문서 스타일 표준안 초안

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

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

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

junghanacs🧠

Table of Contents

Backlinks