‘Mattermost 공식 기술 문서 한글판 by 인포그랩’ 개발 후기(feat. GPT & RST)

인포그랩은 지난 4월 ‘Mattermost 공식 기술 문서 한글판 by 인포그랩(이하 Mattermost 공식 기술 문서 한글판)’이라는 서비스를 선보였는데요. 이는 OpenAI의 생성형 인공지능(AI) 모델 GPT로 Mattermost 기술 문서 총 600개를 한글로 자동 번역해 제공합니다. Mattermost는 미 항공우주국(NASA)과 삼성전자가 사용하는 글로벌 기업용 메신저인데요. 인포그랩은 Mattermost의 공식 리셀러로, 국내 사용자에게 이 서비스를 널리 알리고 편리한 이용을 돕고자 Mattermost 공식 기술 문서 한글판을 개발했습니다.

저는 이 서비스의 개발 과정에서 AI 번역 로직 구현과 RST(reStructuredText) 문법 교정 스크립트 개발 업무를 수행했는데요. 이번 Mattermost 기술 문서 번역 작업은 RST 형식의 기술 문서를 가공하는 데 중점을 뒀습니다. 이 작업은 지난 프로젝트인 ‘GitLab 공식 기술 문서 한글판 by 인포그랩(이하 GitLab 공식 기술 문서 한글판)’에 이어 진행했는데요. 이제 인포그랩 내부에 기술 문서 번역 자동화 워크플로가 정착했고요. AI 번역 작업에 요령이 생겨 이번에는 RST 문법을 정확히 이해하고, 효과적으로 변환하는 데 주력했습니다.

RST 형식의 기술 문서를 GPT로 번역하는 과정은 녹록지 않았는데요. 오늘 그 이유를 설명해 드리려 합니다. 지금부터 제가 Mattermost 기술 문서를 번역하며 겪은 시행착오와 이를 해결한 과정을 자세히 말씀드리겠습니다(Mattermost 공식 기술 문서 한글판의 개발 배경은 'Mattermost 공식 기술 문서 한글판 by 인포그랩’을 소개합니다'를 봐주시면 좋겠습니다. 😊).

번역용 프롬프트 작성했지만

저는 GPT에 입력할 기술 문서 번역용 프롬프트를 작성하기 위해 Mattermost 기술 문서 구조를 먼저 파악했습니다. Mattermost 기술 문서는 Markdown 형식이 아닌 RST 형식인데요. 저는 ‘RST 형식이라고 Markdown 형식과 얼마나 다르겠어’라고 생각했고요. 이에 GitLab 기술 문서를 GPT로 번역할 때 사용한 프롬프트를 Mattermost 기술 문서 번역용으로 수정, GPT에 적용했습니다. 프롬프트에는 역할, 지켜야 할 규칙, 예시를 입력했고요. 관련 응답만 생성하도록 설정했죠.

그 결과..! 멀쩡하게 진행되던 Mattermost docs site의 빌드가 실패하고 말았습니다. 😢 

Mattermost docs site의 빌드 실패 현장

Warning 단계 이상의 오류(심각한 문법 깨짐, 템플릿 문법과의 상호작용 이상 추정)가 다량으로 발생했는데요. 이는 제가 RST 문법의 특수성과 Mattermost docs site의 구조를 잘 몰랐기에 발생한 오류였습니다.

RST 문법 특수성 알아보니

RST 형식은 Python 프로그래밍 언어 커뮤니티에서 기술 문서에 주로 사용하는, 텍스트 데이터의 파일 형식입니다. 몇 가지 문법을 살펴보면 다음과 같은데요.

위 문법은 Markdown 형식으로 아래와 같이 바꿀 수 있습니다.

두 형식의 차이가 보이시나요? RST 형식으로 된 기술 문서를 어떠한 가공 없이 GPT로 번역하면 문법이 깨져 문서가 흐트러지는데요. 맨 처음 예시로 든 RST 형식의 테이블에서 ‘John’이라는 글자가 입력된 칸의 공백을 한 칸 지워보겠습니다(아래 두 번째 이미지 참조).

RST 형식 테이블에서 ‘John’이 입력된 칸의 공백을 지우기 전 모습(왼쪽), 웹사이트에 테이블이 정상적으로 적용된 모습(오른쪽)

RST 형식의 테이블에서 ‘John’이 입력된 칸의 공백을 한 칸 지운 모습(왼쪽), 웹사이트에 테이블이 사라진 모습(오른쪽)

위 이미지에서 보다시피 RST 형식의 테이블은 칸 오른쪽의 세로줄이 칸 아래의 +-----+ 길이와 딱 맞게 정렬돼야 GPT로 번역할 때 테이블로 인식되고요. 그 결과, 웹사이트에도 정상적으로 적용됩니다. 이 세로줄이 +-----+ 길이에 맞춰 정렬되지 않으면 테이블로 인식되지 않고요. 웹사이트에도 테이블이 나타나지 않죠.

이는 Mattermost 기술 문서를 GPT로 번역할 때 다음 문제를 낳았는데요. 예를 들어, GPT는 ‘hello’를 ‘안녕하세요’로 번역하죠. 이 단어가 RST 형식의 테이블 밖에 있으면 GPT로 번역할 때, 결과에 영향을 주지 않는데요. 이 단어가 RST 형식의 테이블 안에 있으면, 번역할 때 글자 수가 바뀌어 테이블 칸 오른쪽의 세로줄이 칸 아래의 +-----+ 길이에 맞게 정렬되지 않고요. 그 결과, 웹사이트에 테이블이 정상적으로 적용되지 않습니다(아래 두 번째 이미지 참조).

RST 형식의 테이블에 있는 단어를 번역하기 전 모습(왼쪽), 웹사이트에 테이블이 정상적으로 적용된 모습(오른쪽)

RST 형식의 테이블에 있는 단어를 번역한 후 모습(왼쪽), 웹사이트에 테이블이 사라진 모습(오른쪽)

아울러 이는 에러를 발생시키지도 않아 ‘어떤 파일에서 문법이 깨졌는지’ 바로 파악하기도 어려운데요. 이를 확인하려면 모든 번역본을 원본 문서와 비교해야 하죠. 이는 Mattermost 기술 문서 번역 과정에서 시간이 굉장히 오래 걸리고, 집중력을 상당히 기울여야 하는 작업이었습니다.

개선 방안 찾아 삼만리

저는 테이블이 깨진 Mattermost 기술 문서 번역본을 확인하며, ‘어떠한 요소가 번역 과정에서 깨졌는지’, ‘어떠한 점이 실행에 영향을 주는지’ 하나하나 살펴보고 기록했습니다. RST 문법도 공부하고요. 관련 문서를 꼼꼼히 읽었습니다. 학습 결과, Mattermost 기술 문서를 번역할 때 다음 사항을 고려해야 한다는 걸 깨달았는데요.

- `__` 뒤에 띄어쓰기
- ** 앞, 뒤에 띄어쓰기
- < 앞에 띄어쓰기
- ____ 다음에 엔터키 치기
- RST 파일 상단, 하단에 ``` 를 붙일 때가 있음
    1. 글을 나눠서 번역하므로 ```가 중복으로 붙거나 문서 중간에 들어갈 때도 있음
    2. 명시해 두고 정규 표현식으로 추가 Fix하기
- ******* 라는 문법도 있어서 ** 뒤에 띄어 쓰는 정규 표현식 수정하기
- `*텍스트*` 뒤에도 띄어쓰기
- __ 가 _ 로 변경될 때가 있음
- 링크를 거는 `를 빼먹을 때가 있음. 하나씩 추가되기도 함
- 링크 뒤에 띄어쓰기
- 코드 블록이 번역될 때가 있음
- 테이블이 align을 그대로 맞춰야 해 안 깨지는 일이 적음
- 테이블 형식이 한 가지가 아님. 여러 테이블 형식을 고려해야 함

저는 위 내용을 GPT가 이해하도록 프롬프트에 관련 내용을 추가했고요. 번역을 계속 테스트하며 프롬프트를 개선했습니다. 그 결과, 약 2000자 분량의 최종 프롬프트를 완성했죠. 프롬프트를 수정해도 GPT의 할루시네이션(환각 현상) 때문에 종종 문법이 깨졌는데요. 이 문제를 해결하고자 Python을 사용해 교정 스크립트를 개발했습니다. 이를 번역 과정에 추가하니 문법이 깨지는 문제가 많이 해결됐습니다.

계속 깨지는 테이블

프롬프트를 개선해 테이블이 깨지는 일은 줄었지만, 이 문제는 여전히 골칫덩어리로 남았습니다. 여기에는 문법을 교정하는 스크립트 문제도 한몫했는데요.

예를 들어, **안녕하세요.**John입니다.라는 문장을 문법에 맞게 수정하면 **안녕하세요.** John입니다.가 됩니다. 이 문장이 테이블 안에 있으면 공백이 추가돼 칸 오른쪽의 세로줄이 칸 아래의 +-----+ 길이에 맞게 정렬되지 않고요. 테이블이 깨지죠. 그러나 문장을 문법에 맞게 수정하지 않으면 **가 테이블 안에서 볼드 처리되지 않거나, 하이퍼링크가 풀리는 문제도 생깁니다.

테이블이 단순하고 간단하면, 문제를 해결하기가 어렵지 않습니다. GPT에 프롬프트로 예시를 들어주고 ‘RST 문법을 지켜 테이블 형식을 맞춰달라’고 지시하면, GPT가 이에 맞춰 테이블이 깨지지 않도록 번역하니까요. 그러나 테이블이 크고 복잡하면, GPT가 테이블에 적용된 RST 문법을 고려하지 않고요. 테이블 형식도 맞추지 않아 번역 결과, 테이블이 깨질 때가 많았습니다.

저는 이 문제를 고민하다가 인포그랩 멤버들에게 조언을 구했는데요. ‘RST 형식의 테이블을 다른 형식으로 파싱하고, 그걸 번역하자’는 아이디어를 얻었습니다. 이를 곧바로 실행에 옮겼는데요. 먼저 RST 형식의 테이블을 찾아 HTML 형식으로 파싱했고요. 그 HTML 버전을 번역한 다음, 다시 RST 형식으로 파싱했죠.

RST 형식의 테이블을 HTML 형식으로 파싱→HTML 버전 번역→다시 RST 형식으로 파싱한 결과

이 방법을 사용하면 GPT 토큰값은 1.5배 더 들어가는데요. 그래도 테이블이 깨지는 문제를 해결할 수 있어 저는 이 방법을 선택했습니다. RST 형식의 테이블을 HTML 형식으로 변환하면서 번역에 이상은 없었고요. 마침내 테이블이 깨지는 문제를 상당수 해결했습니다.

우여곡절 끝에 개발 마무리

아쉽지만 이러한 방법을 사용해도 깨지는 테이블이 1~2개 있었습니다. 1000줄을 훌쩍 넘고, RST 문법이 가득한 테이블이었죠. 이런 테이블까지 완벽하게 100% 자동 번역하기는 어려웠습니다. 일부는 GPT로 번역하되, 테이블이 깨지는 건 수동으로 바로잡았습니다.

이러한 시행착오를 거쳐 모든 Mattermost 기술 문서를 RST 문법이 깨지지 않도록 수정했고요. 마침내 빌드해 정적 배포를 진행했습니다. GitLab에서 CI/CD 파이프라인을 구축해 CloudFront로 정적 배포되도록 했고요. 프로덕션 배포로 모든 일이 끝났죠.

최종 배포된 Mattermost 공식 기술 문서 한글판 메인 페이지

맺음말

Mattermost 기술 문서를 GPT로 번역하면서 ‘왜 에러가 발생했는지’ 몰라 많이 헤맸습니다. ‘사이즈가 매우 큰 테이블을 교정하려면 어떻게 해야 하지?’, ‘프롬프트를 어떻게 수정해야 할까?’ 고민하며 시행착오를 연달아 겪었는데요. 이러한 고민과 문제 해결 과정이 주니어 엔지니어인 제게 굉장히 좋은 경험이었습니다. 이번 경험을 토대로, 다양한 AI 도구를 학습해 이를 잘 활용하는 프로젝트를 수행하고 싶습니다. 🤭

제가 생각하는 Mattermost 공식 기술 문서 한글판의 과제는 다음과 같습니다. 첫째, 어떠한 RST 형식의 테이블이든 깨지지 않고 잘 번역되도록 스크립트를 만들 것. 둘째, 프롬프트를 개선해 RST 형식의 기술 문서를 번역할 때 할루시네이션을 줄여 번역 품질을 향상하고, 100% 번역 자동화를 구현하는 것입니다. 지금까지 ‘Mattermost 공식 기술 문서 한글판 by 인포그랩 개발 후기’를 읽어주셔서 감사합니다.

참고 자료

1. Mattermost 공식 기술 문서 한글판 by 인포그랩
2. ‘Mattermost 공식 기술 문서 한글판 by 인포그랩’을 소개합니다
3. 인포그랩, 'Mattermost 공식 기술 문서 한글판' 론칭
4. NASA와 삼성이 선택한 메신저 ‘Mattermost’ 알아보기
5. Why Mattermost
6. Mattermost 공식 홈페이지
7. Mattermost Documentation
8. FILEFORMAT - RST 파일 정보

 DevOps를 가속화하는 메시징 플랫폼, Mattermost! 인포그랩과 함께 도입하세요.