readme-i18n

Tổng quan về skill readme-i18n

readme-i18n làm được gì

readme-i18n là một skill chuyên dụng để biến một README.md theo kiểu GitHub thành một bộ README đa ngôn ngữ dễ duy trì về lâu dài. Đây không phải công cụ bản địa hóa ứng dụng nói chung. Nhiệm vụ cốt lõi của nó là dịch file README nguồn, tạo các file song song như README.zh.md, giữ nguyên cơ chế Markdown và cách repo vận hành, đồng thời thêm hoặc chuẩn hóa một bộ chọn ngôn ngữ dùng chung trên mọi biến thể.

Ai nên dùng readme-i18n

Skill này phù hợp với maintainer, người đóng góp mã nguồn mở và AI agent đang làm tài liệu cho repository, khi mục tiêu thực sự không chỉ là “dịch văn bản” mà là “phát hành các file README đã dịch mà vẫn hoạt động đúng trên GitHub”. Nếu bạn cần badges, links, code fences, quy ước đặt tên file và bộ chuyển ngôn ngữ luôn nhất quán, thì readme-i18n là điểm khởi đầu tốt hơn một prompt dịch thuật chung chung.

Bài toán thực tế mà skill này giải quyết

Phần lớn các lần dịch README bị hỏng ở cấu trúc chứ không phải từ vựng. Người dùng cần một quy trình có thể:

• coi một file là nguồn chuẩn duy nhất
• giữ thứ tự section đồng bộ với bản gốc
• bảo toàn commands, paths, code và cơ chế liên kết
• cập nhật nhất quán mọi bản ngôn ngữ
• tránh trùng lặp hoặc làm hỏng bộ chọn ngôn ngữ

Đó chính là giá trị thực tiễn của readme-i18n skill.

Vì sao skill này khác với một prompt thông thường

Điểm khác biệt lớn nhất nằm ở logic ra quyết định. Skill hướng dẫn agent cần giữ nguyên chính xác những gì, khi nào chỉ nên hỏi làm rõ một lần, cách suy ra quy ước từ các file sẵn có và cách cập nhật selector ngay tại chỗ thay vì tạo thêm một selector mới. Các tài liệu tham chiếu đi kèm đặc biệt hữu ích khi triển khai thực tế, vì chúng giảm đáng kể việc phải đoán vị trí đặt selector và cách xử lý Markdown an toàn khi dịch.

Cách dùng skill readme-i18n

Bối cảnh cài đặt readme-i18n

Hãy cài skill này từ repository xixu-me/skills trong bất kỳ môi trường tương thích Skills nào bạn đang dùng. Nếu hệ thống của bạn hỗ trợ cài trực tiếp từ GitHub, cách phổ biến là:

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

Nếu môi trường của bạn quản lý skills theo cách khác, hãy dùng URL repo https://github.com/xixu-me/skills/tree/main/skills/readme-i18n làm nguồn tham chiếu và nạp skill từ skills/readme-i18n.

Các file nên đọc trước lần dùng đầu tiên

Với skill này, lộ trình đọc nhanh nhưng nhiều tín hiệu nhất là:

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

Thứ tự này rất quan trọng. SKILL.md cho bạn quy trình làm việc, tài liệu selector cho biết hình dạng block và vị trí đặt mong đợi, còn checklist bảo toàn chỉ rõ những gì bắt buộc phải giữ nguyên.

readme-i18n cần đầu vào gì

Skill hoạt động tốt nhất khi bạn cung cấp:

• đường dẫn README nguồn, thường là README.md
• ngôn ngữ nguồn
• ngôn ngữ hoặc các ngôn ngữ đích
• glossary hoặc các thuật ngữ không được dịch
• quy ước đặt tên file hiện có nếu repo đã bản địa hóa README từ trước

Nếu bạn không nêu ngôn ngữ đích, skill được thiết kế để kiểm tra trước các file dịch sẵn có, selector, tên file, issues hoặc quy ước trong repo. Nếu vẫn chưa xác định được ngôn ngữ, nó nên hỏi lại một lần thay vì tự bịa ra đích dịch.

Những giả định mặc định quan trọng cần biết

Các mặc định được ghi rõ trong tài liệu đều thực tế và rất đáng biết trước khi chạy readme-i18n:

• README.md ở thư mục gốc là nguồn chuẩn duy nhất, trừ khi bạn nói khác
• ngôn ngữ nguồn được mặc định là tiếng Anh nếu không có sự mơ hồ
• thứ tự section phải bám theo bản nguồn
• nếu repo đã có quy ước đặt tên đa ngôn ngữ, cần giữ nguyên thay vì ép sang cách mới

Những mặc định này giúp skill an toàn hơn với các repo đang tồn tại so với một yêu cầu dịch trống thông tin.

Cách viết prompt cho readme-i18n hiệu quả

Một yêu cầu yếu là: “Dịch README của tôi sang tiếng Trung.”

Một prompt readme-i18n usage tốt hơn sẽ là:

• dịch README.md từ tiếng Anh sang tiếng Trung giản thể
• tạo README.zh.md
• giữ nguyên commands, paths, badge URLs, code fences và relative links
• thêm bộ chọn ngôn ngữ ở đầu cho cả hai file
• giữ thứ tự heading giống hệt bản gốc
• không dịch tên sản phẩm AcmeCLI hoặc env vars
• tuân theo mọi quy ước đặt tên file sẵn có nếu tìm thấy

Mức độ cụ thể bổ sung này cải thiện trực tiếp chất lượng đầu ra vì nó khớp với các quy tắc bảo toàn và selector của skill.

Quy trình mẫu để dịch

Một quy trình readme-i18n for Translation thực tế sẽ là:

1. Xác định README nào là nguồn chuẩn duy nhất.
2. Kiểm tra xem đã có các bản dịch hay chưa.
3. Nhận diện mẫu tên file của repo và kiểu selector hiện tại.
4. Chỉ dịch phần nội dung ngôn ngữ cho người đọc.
5. Giữ nguyên tuyệt đối code, commands, URLs và file paths.
6. Thêm hoặc chuẩn hóa một block selector ở gần đầu mỗi biến thể.
7. Kiểm tra links, định dạng và tính nhất quán giữa tất cả các file.

Đây là mô hình tư duy đúng: không phải “dịch văn bản”, mà là “duy trì cả một họ README”.

Bộ chọn ngôn ngữ nên hoạt động như thế nào

File hỗ trợ giá trị nhất trong skill này là tài liệu tham chiếu selector. Tài liệu khuyến nghị chỉ có một block selector ở gần đầu mỗi biến thể README, thường nằm sau tiêu đề và cụm badge, với các marker ổn định:

<!-- README-I18N:START -->
<!-- README-I18N:END -->

Các marker này rất quan trọng vì những lần chạy sau có thể cập nhật selector ngay tại chỗ. Ngôn ngữ hiện tại nên được nhấn mạnh và không gắn link; các ngôn ngữ còn lại phải có link. Thứ tự ngôn ngữ cần được giữ giống nhau trên mọi biến thể.

Những gì bắt buộc phải giữ nguyên tuyệt đối

Checklist bảo toàn là phần mang tính quyết định khi áp dụng readme-i18n guide này. Trong thực tế, không được dịch:

• inline code
• fenced code blocks
• commands, flags, env vars, paths
• badge URLs và query params
• đường dẫn nguồn ảnh
• cấu trúc bảng
• cơ chế raw HTML

Hãy dịch phần văn xuôi hiển thị cho người đọc, nhưng phải giữ nguyên những cơ chế giúp README hoạt động đúng.

Các quy ước repo mà readme-i18n tôn trọng

Nếu repo đã dùng một quy ước đặt tên khác với mặc định:

• README.md
• README.zh.md
• README.es.md

thì skill phải giữ nguyên quy ước đó. Điều này đặc biệt quan trọng với các repo đã có bản địa hóa một phần, có tham chiếu trong CI, hoặc có kỳ vọng từ cộng tác viên gắn với tên file.

Khi nào readme-i18n tiết kiệm thời gian nhất

Skill này phát huy giá trị rõ nhất khi bạn gặp một trong các điểm nghẽn sau:

• bạn cần nhiều file README đã bản địa hóa luôn được giữ đồng bộ
• repo đã có bộ chuyển ngôn ngữ lộn xộn hoặc bị trùng
• các bản dịch trước đây làm hỏng Markdown hoặc links
• bạn muốn việc cập nhật có thể lặp lại theo quy trình thay vì sửa tay từng lần

Nếu bạn chỉ cần một bản dịch sơ bộ để đọc hiểu README cho riêng mình, skill này có lẽ hơi nặng quy trình hơn mức cần thiết.

Câu hỏi thường gặp về skill readme-i18n

readme-i18n có phù hợp với người mới bắt đầu không?

Có, nếu mục tiêu của bạn đúng là bản địa hóa README. Skill này thu hẹp bài toán thành đầu vào rõ ràng và các quy tắc bảo toàn cụ thể, nên dễ tiếp cận hơn việc tự nghĩ ra toàn bộ quy trình dịch. Dù vậy, người mới vẫn cần rà soát đầu ra, đặc biệt là đích của links, heading và độ nhất quán của selector.

Khi nào nên dùng readme-i18n thay vì một prompt dịch thông thường?

Hãy dùng readme-i18n khi bản README đã dịch sẽ được commit vào repo. Một prompt thông thường có thể dịch quá tay, sửa cả ví dụ code, làm hỏng badge links hoặc quên điều hướng giữa các file. Skill này phù hợp hơn khi tính chính xác của đầu ra quan trọng hơn tốc độ.

readme-i18n có chỉ dùng cho repository trên GitHub không?

Skill này được tối ưu cho các README kiểu repository trên GitHub và các quy ước Markdown tương ứng. Nó vẫn có thể hữu ích trên các nền tảng Git khác, nhưng các giả định của nó khớp nhất với các repo mã nguồn mở dựa trên README.md, chứ không phải full docs site hay hệ thống bản địa hóa sản phẩm.

readme-i18n có xử lý được cả bộ tài liệu đầy đủ không?

Không. Đây là một quy trình tập trung vào README. Nếu bạn cần i18n cho website, ứng dụng hoặc toàn bộ hệ thống tài liệu, thì readme-i18n skill là quá hẹp. Điểm mạnh của nó là giữ cho một tài liệu landing của repository và các file song song đã bản địa hóa luôn nhất quán.

Tôi có thể dùng những ngôn ngữ nào?

Skill này không phụ thuộc vào ngôn ngữ, miễn là bạn chỉ rõ ngôn ngữ đích hoặc repo đã thể hiện điều đó đủ rõ. Nó chủ động tránh tự suy diễn ngôn ngữ đích khi repo không cung cấp đủ căn cứ.

readme-i18n có thể cập nhật một thiết lập README đa ngôn ngữ đã có sẵn không?

Có, và đây là một trong những tình huống dùng tốt nhất. Skill được thiết kế để kiểm tra các file dịch và selector hiện có, giữ nguyên quy ước đặt tên, đồng thời chuẩn hóa bộ chuyển ngôn ngữ hiện tại thay vì chèn thêm một bộ thứ hai.

Khi nào readme-i18n không phù hợp?

Nên bỏ qua khi:

• bạn chỉ muốn một bản dịch đọc hiểu không chính thức
• tài liệu của bạn không nằm trong README
• bạn cần quản lý thuật ngữ trên một kho tài liệu lớn
• repo của bạn không muốn có language-selector links trong các file README

Trong những trường hợp đó, một prompt nhẹ hơn hoặc một quy trình bản địa hóa tài liệu rộng hơn có thể phù hợp hơn.

Cách cải thiện skill readme-i18n

Cung cấp ràng buộc nguồn mạnh hơn cho readme-i18n

Đầu vào tốt hơn sẽ cho ra các biến thể README tốt hơn. Hãy nêu rõ:

• đường dẫn file nguồn chính xác
• các locale đích chính xác
• các thuật ngữ tuyệt đối không dịch
• tên ngôn ngữ tự gọi (autonyms) mà bạn muốn dùng
• có nên ghi đè file dịch hiện có hay chỉ cập nhật

Cách này giảm lỗi phổ biến nhất: bản dịch đúng nghĩa nhưng hành vi trong repo lại sai.

Cung cấp glossary cho tên riêng và thuật ngữ kỹ thuật

Nếu README của bạn có tên sản phẩm, CLI commands, package names hoặc thuật ngữ chuyên ngành, hãy liệt kê rõ. readme-i18n vốn đã cố giữ nguyên các literal, nhưng một glossary ngắn sẽ giúp nhất quán hơn ở heading, mô tả tính năng và ví dụ.

Nói rõ skill không được đụng vào đâu

Một trong những cách tốt nhất để cải thiện readme-i18n usage là đặt ra ranh giới cứng:

• giữ mọi code block giống hệt từng byte
• bảo toàn relative links
• không đổi tên file nếu không được yêu cầu
• không thay đổi đích badge
• không đảo thứ tự section

Những chỉ dẫn này bám rất sát checklist bảo toàn và ngăn các chỉnh sửa “có vẻ hữu ích” nhưng thực ra gây hại.

Kiểm tra vị trí selector trước khi commit

Một lỗi đầu ra khá thường gặp là bộ chuyển ngôn ngữ bị đặt lệch hoặc bị nhân đôi. Hãy đối chiếu selector được tạo với references/language-selector-reference.md và kiểm tra:

• mỗi file chỉ có một selector
• vị trí đặt nhất quán giữa các biến thể
• ngôn ngữ hiện tại được in đậm, không gắn link
• links trỏ đúng tới tên file song song thực tế

Đây là một bước rà soát nhỏ nhưng hiệu quả rất lớn.

Kiểm tra heading đã bản địa hóa và anchors

Heading sau khi dịch có thể làm thay đổi cách nền tảng sinh anchor, nhất là trên các hệ thống tạo fragment ID từ chính nội dung heading. Skill cố gắng giữ nguyên hệ phân cấp heading, nhưng bạn vẫn nên kiểm tra các internal heading links sau khi dịch, đặc biệt với các README dài.

Lặp lại từ thay đổi ở nguồn, không sửa vá riêng lẻ

Để dễ bảo trì lâu dài, hãy giữ README.md làm nguồn chuẩn duy nhất và chạy lại readme-i18n từ các cập nhật ở nguồn, thay vì chỉnh tay từng file bản địa hóa một cách độc lập. Cách làm này giúp thứ tự section, nội dung selector và thuật ngữ luôn đồng bộ theo thời gian.

Dùng đối chiếu song song sau lần chạy đầu tiên

Sau lượt chạy đầu, hãy so sánh file nguồn và file đích theo các tiêu chí:

• số lượng section giống nhau
• số lượng code block giống nhau
• bảng biểu và cấu trúc danh sách giống nhau
• hình ảnh và badges giống nhau
• selector links hoạt động

Cách này giúp phát hiện lỗi hồi quy về cấu trúc nhanh hơn nhiều so với việc đọc lại từng câu.

Cải thiện các lần chạy sau bằng cách nêu rõ quy ước của repo

Nếu repo của bạn có mẫu đa ngôn ngữ không tiêu chuẩn, hãy nói thẳng điều đó trong prompt ở lần gọi readme-i18n tiếp theo. Ví dụ:

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

Skill sẽ đáng tin cậy hơn nhiều khi các quy ước của repo được nêu rõ thay vì để nó tự suy ra.