Sinh khóa dịch từ danh sách câu: cách đặt tên khóa và những chỗ phải sửa tay
Dán danh sách câu, mỗi dòng một câu, công cụ sinh khóa cho từng dòng theo quy ước đặt tên bạn chọn rồi ghép thành tệp ngôn ngữ ở dạng JSON, YAML hoặc TypeScript. Đây là bước tạo bản nháp nhanh cho tệp dịch, còn việc đặt tên khóa cho bền và xử lý số nhiều vẫn cần bạn quyết định.
Tính năng nổi bật
- Nhận danh sách câu theo dòng, mỗi dòng thành một cặp khóa và giá trị
- Bốn quy ước đặt tên khóa: chữ lạc đà, gạch dưới, dấu chấm và gạch nối
- Ô đặt không gian tên, khi có thì toàn bộ khóa được bọc trong một tầng mang tên đó
- Ba định dạng đầu ra: JSON thụt lề hai khoảng trắng, YAML và mô đun TypeScript
- Bản TypeScript xuất ra kèm khai báo hằng và ghi chú kiểu bất biến ở cuối
- Nút sao chép toàn bộ kết quả và nút tải tệp với phần mở rộng khớp định dạng đã chọn
- Bỏ qua các dòng trống nên bạn dán thoải mái từ bảng tính hay tài liệu
- Chạy hoàn toàn trong trình duyệt, chuỗi nội dung không gửi lên máy chủ
Vì sao khâu tạo khóa dịch lại tốn thời gian một cách vô lý
Khi đưa một giao diện đang viết cứng chữ sang cơ chế đa ngôn ngữ, phần khó về kỹ thuật thường không nhiều, nhưng phần cơ học thì rất mệt. Bạn phải mở từng tệp giao diện, chép từng câu ra, nghĩ một cái tên khóa cho nó, gõ tên khóa vào tệp ngôn ngữ, gõ lại nội dung làm giá trị, rồi quay lại thay câu trong giao diện bằng lời gọi hàm dịch. Với một màn hình có bốn mươi câu thì đó là một buổi chiều gõ máy thuần túy, và trong lúc gõ tay rất dễ sai chính tả tên khóa khiến giao diện hiện ra đúng tên khóa thay vì hiện chữ. Công cụ này gánh phần cơ học đó: bạn quét hết chữ trên màn hình vào một danh sách, dán vào đây, chọn quy ước, rồi có ngay khung tệp ngôn ngữ để dán vào dự án và sửa lại tên những khóa quan trọng.
Lợi ích khi sử dụng
- Bỏ được khâu gõ tay tên khóa cho hàng chục câu một lúc
- Ba định dạng đầu ra nên dùng được với hầu hết thư viện đa ngôn ngữ phổ biến
- Tên khóa sinh theo một quy tắc cố định nên cả nhóm có kết quả giống nhau
- Có tệp nháp trong tay thì việc rà soát và đặt lại tên nhanh hơn viết từ đầu
- Chuỗi nội dung nội bộ không rời khỏi trình duyệt của bạn
Cách sinh một tệp ngôn ngữ nháp
- 1Gom các câu cần dịch của một màn hình vào danh sách, mỗi câu một dòng, ưu tiên dùng bản tiếng Anh làm nguồn.
- 2Dán danh sách vào ô nhập, các dòng trống sẽ tự bị bỏ qua.
- 3Đặt tên không gian tên theo màn hình hoặc theo tính năng, ví dụ auth, checkout hay common.
- 4Chọn quy ước đặt tên khóa cho khớp với quy ước sẵn có trong dự án, rồi chọn định dạng đầu ra.
- 5Sao chép hoặc tải tệp về, sau đó soát lại từng khóa, đổi tên những khóa quá dài và bổ sung các trường hợp số nhiều.
Công cụ sinh khóa theo đúng bốn bước này
Biết chính xác quy tắc sẽ giúp bạn đoán trước kết quả thay vì thử rồi sửa. Bước một, toàn bộ dòng được chuyển thành chữ thường và cắt bỏ khoảng trắng thừa ở hai đầu. Bước hai, mọi ký tự không phải chữ cái không dấu, chữ số, dấu gạch dưới, khoảng trắng hoặc dấu gạch nối đều bị xóa; nghĩa là dấu chấm hỏi, dấu chấm than, dấu phẩy, dấu hai chấm và dấu nháy đều biến mất. Bước ba, mọi cụm khoảng trắng liên tiếp được thay bằng một dấu gạch dưới. Bước bốn, tùy quy ước bạn chọn mà dấu gạch dưới được giữ nguyên, đổi thành dấu chấm, đổi thành dấu gạch nối, hoặc bị xóa và viết hoa chữ cái đứng sau để thành chữ lạc đà. Hệ quả thực tế là một câu dài sẽ cho ra một tên khóa rất dài, vì công cụ không cắt bớt từ. Câu hỏi quên mật khẩu trong tiếng Anh sẽ thành một khóa gồm ba từ ghép lại, còn một câu giới thiệu hai dòng sẽ thành khóa dài cả chục từ, khó đọc và khó bảo trì.
Chữ tiếng Việt có dấu bị xóa, và đây là điều bạn phải biết trước
Đây là giới hạn quan trọng nhất của công cụ với người dùng Việt Nam. Bước lọc ký tự dùng lớp ký tự chữ và số theo bảng mã tiếng Anh, không bật chế độ hỗ trợ ký tự Unicode mở rộng, nên mọi nguyên âm có dấu và chữ đ đều bị coi là ký tự đặc biệt và bị xóa thay vì được chuyển thành ký tự không dấu tương ứng. Kết quả là một dòng như Đăng nhập sẽ cho ra một tên khóa cụt lủn không còn nhận ra nghĩa gốc, và nếu bạn dán cả màn hình tiếng Việt vào thì rất nhiều dòng khác nhau có thể cho ra cùng một tên khóa rồi ghi đè lẫn nhau. Có hai cách xử lý. Cách thứ nhất, và cũng là cách nên làm về lâu dài, là dùng bản tiếng Anh làm ngôn ngữ nguồn để sinh khóa, rồi tạo tệp tiếng Việt bằng cách chép khung khóa đó và thay giá trị. Cách thứ hai là chạy danh sách tiếng Việt qua một bước bỏ dấu trước khi dán vào đây, sau đó soát lại tên khóa bằng tay.
Quy ước dấu chấm ở đây không tạo cấu trúc lồng nhau
Khi bạn chọn quy ước dấu chấm, công cụ chỉ thay các dấu gạch dưới trong một tên khóa bằng dấu chấm, chứ không tách chuỗi đó thành nhiều tầng đối tượng. Nghĩa là bạn nhận được một khóa phẳng có chứa dấu chấm bên trong, chẳng hạn một khóa dạng welcome.to.our.site nằm ngang hàng với các khóa khác, chứ không phải một đối tượng welcome chứa đối tượng to chứa đối tượng our. Điều này rất dễ gây lỗi vì phần lớn thư viện đa ngôn ngữ mặc định hiểu dấu chấm là dấu phân tách tầng khi tra khóa; khi đó thư viện sẽ đi tìm đường dẫn nhiều tầng, không thấy, và trả về chính tên khóa. Có ba cách xử lý: tắt tính năng phân tách theo dấu chấm trong cấu hình thư viện, đổi sang quy ước gạch dưới hoặc gạch nối rồi tự dựng cấu trúc lồng, hoặc dùng dấu chấm một cách có chủ ý bằng cách nhập sẵn các đoạn phân tầng và tự sửa lại tệp sau khi sinh. Trước khi dán vào dự án, hãy thử một khóa để chắc chắn thư viện tra đúng.
Đặt tên khóa theo vai trò, không đặt theo nội dung câu
Đây là quy tắc quan trọng nhất trong quản lý tệp ngôn ngữ, và cũng là chỗ bản nháp do công cụ sinh ra cần được sửa lại. Vì công cụ lấy chính nội dung câu làm tên khóa, bạn sẽ có những khóa kiểu nhấn vào đây để đăng ký ngay hôm nay. Sáu tháng sau khi bộ phận nội dung đổi câu đó thành một lời mời khác, tên khóa vẫn giữ nguyên và bắt đầu nói dối về nội dung nó chứa, hoặc tệ hơn là ai đó tạo một khóa mới còn khóa cũ nằm lại trong tệp mãi mãi. Cách đặt bền hơn là mô tả vị trí và vai trò trong giao diện, ví dụ một khóa cho nhãn nút gửi biểu mẫu đăng ký, một khóa cho tiêu đề khối quảng bá trên trang chủ. Cấu trúc thông dụng là ba tầng gồm màn hình, thành phần và vai trò. Ngoài ra hãy tránh gộp các mẩu câu rời rồi nối lại trong mã, vì trật tự từ giữa các ngôn ngữ khác nhau và câu ghép sẽ vỡ nghĩa khi dịch; luôn để một câu hoàn chỉnh trong một khóa.
Những thứ một tệp ngôn ngữ thật cần mà công cụ chưa sinh
Thứ nhất là số nhiều. Tiếng Anh có hai dạng, nhưng nhiều ngôn ngữ có ba tới sáu dạng tùy con số, nên thư viện đa ngôn ngữ đều có cú pháp riêng cho việc này và bạn phải viết tay sau khi sinh khung. Thứ hai là chỗ chèn biến, ví dụ tên người dùng hay số lượng đơn hàng; mỗi thư viện dùng một kiểu đánh dấu chỗ chèn riêng, công cụ giữ nguyên chữ nên bạn phải tự thêm. Thứ ba là định dạng ngày giờ, tiền tệ và số, những thứ không nên viết cứng vào chuỗi mà nên để thư viện định dạng theo vùng. Thứ tư, và đây là một lỗi kỹ thuật cần lưu ý, phần đầu ra dạng YAML và TypeScript bọc giá trị trong dấu nháy kép mà không xử lý dấu nháy kép có sẵn trong câu, nên một câu chứa dấu nháy kép sẽ làm hỏng cú pháp và bạn phải sửa tay. Cuối cùng, nếu hai dòng khác nhau cho ra cùng một tên khóa thì dòng sau ghi đè dòng trước một cách âm thầm, nên hãy đếm lại số cặp trong kết quả so với số dòng đã dán.
Câu hỏi thường gặp (FAQ)
Vì sao khóa sinh từ câu tiếng Việt bị mất chữ?
Vì bước lọc ký tự chỉ giữ chữ cái không dấu, chữ số, dấu gạch dưới, khoảng trắng và gạch nối, nên mọi nguyên âm có dấu và chữ đ bị xóa thay vì được chuyển thành ký tự không dấu. Cách xử lý là dùng bản tiếng Anh làm ngôn ngữ nguồn để sinh khóa, hoặc bỏ dấu danh sách trước khi dán vào đây.
Chọn quy ước dấu chấm thì tệp có tự lồng nhiều tầng không?
Không. Công cụ chỉ thay dấu gạch dưới trong tên khóa bằng dấu chấm, kết quả vẫn là khóa phẳng có chứa dấu chấm. Phần lớn thư viện lại hiểu dấu chấm là dấu phân tách tầng khi tra khóa, nên chúng sẽ tìm không thấy và trả về chính tên khóa. Hãy thử một khóa trước khi dán cả tệp vào dự án.
Số dòng tôi dán vào nhiều hơn số khóa sinh ra, vì sao?
Vì có hai dòng cho ra cùng một tên khóa và dòng sau ghi đè dòng trước. Trường hợp này hay xảy ra với các câu chỉ khác nhau ở dấu câu, hoặc với danh sách tiếng Việt sau khi bị xóa dấu. Hãy đếm lại số cặp trong kết quả so với số dòng đã dán và đặt tên riêng cho những câu bị trùng.
Nên đặt tên khóa theo nội dung hay theo vị trí?
Theo vị trí và vai trò trong giao diện. Khóa lấy từ chính nội dung câu sẽ nói dối ngay khi bộ phận nội dung đổi câu, và bạn sẽ có những khóa mô tả một đằng chứa một nẻo. Cấu trúc thông dụng là ba tầng gồm màn hình, thành phần và vai trò, ví dụ khóa cho nhãn nút gửi trong biểu mẫu đăng ký.
Không gian tên nên đặt thế nào?
Thường theo màn hình hoặc theo tính năng, cộng thêm một không gian dùng chung cho các chuỗi lặp lại khắp nơi như nút lưu, nút hủy hay thông báo lỗi mạng. Chia theo tính năng còn giúp tải tệp ngôn ngữ theo nhu cầu thay vì tải toàn bộ chuỗi của cả ứng dụng ngay từ lần vào đầu tiên.
Công cụ có xử lý số nhiều không?
Không. Mỗi dòng thành đúng một cặp khóa và giá trị. Tiếng Anh có hai dạng số nhiều nhưng nhiều ngôn ngữ có ba tới sáu dạng tùy con số, nên mỗi thư viện có cú pháp riêng cho việc này và bạn phải viết tay các nhánh số nhiều sau khi sinh xong khung tệp.
Chỗ chèn biến như tên người dùng thì làm sao?
Công cụ giữ nguyên chữ nên bạn phải tự thêm dấu đánh dấu chỗ chèn theo cú pháp của thư viện đang dùng. Nguyên tắc là luôn đặt biến trong một câu hoàn chỉnh, đừng cắt câu thành nhiều mẩu rồi nối trong mã, vì trật tự từ giữa các ngôn ngữ khác nhau và câu ghép sẽ vỡ nghĩa.
Câu có dấu nháy kép làm hỏng tệp xuất ra, xử lý thế nào?
Phần đầu ra dạng YAML và TypeScript bọc giá trị trong dấu nháy kép mà không xử lý dấu nháy kép có sẵn trong câu, nên cú pháp sẽ hỏng. Cách tạm thời là chọn định dạng JSON vì bản này được tạo bằng hàm chuyển đối tượng thành chuỗi nên tự thoát ký tự đúng, sau đó chuyển đổi sang định dạng bạn cần.
Câu dài sinh ra khóa quá dài thì có sao không?
Không gây lỗi nhưng rất khó bảo trì, và những khóa như vậy gần như chắc chắn là loại đặt theo nội dung nên sẽ lỗi thời nhanh. Với các câu dài như đoạn giới thiệu hay điều khoản, hãy đặt lại tên khóa ngắn theo vai trò ngay sau khi sinh, ví dụ một khóa cho đoạn mô tả gói dịch vụ cơ bản.
Có nên xóa dấu câu khỏi tên khóa không?
Nên, và công cụ làm sẵn điều đó. Tên khóa chỉ nên gồm chữ cái, chữ số và một loại dấu phân tách, vì dấu chấm hỏi hay dấu nháy trong tên khóa gây rắc rối khi tra cứu, khi xuất sang định dạng khác và khi các công cụ dịch tự động xử lý tệp.
Tệp tải về có tên và phần mở rộng gì?
Tệp luôn có tên là translations kèm phần mở rộng khớp định dạng bạn chọn, tức json, yaml hoặc ts. Khi đưa vào dự án, bạn nên đổi tên theo mã ngôn ngữ và không gian tên, chẳng hạn đặt trong thư mục theo mã ngôn ngữ rồi đặt tên tệp theo tên không gian tên.
Nội dung tôi dán vào có bị gửi đi đâu không?
Không. Việc sinh khóa và ghép tệp đều chạy bằng JavaScript ngay trong trình duyệt, không có bước gọi máy chủ, và tệp tải về cũng được tạo tại chỗ. Bạn có thể dán chuỗi giao diện của sản phẩm chưa công bố mà không lo lộ thông tin.
Từ khóa liên quan
- tạo translation key
- i18n key generator
- đa ngôn ngữ trong web
- cách đặt tên translation key
- file ngôn ngữ json
- i18next namespace
- quy ước đặt tên khóa dịch
- chuyển giao diện sang đa ngôn ngữ
- localization là gì
- số nhiều trong i18n
- nội suy biến trong chuỗi dịch
- tệp locale yaml
- xuất translations typescript
- bỏ dấu tiếng Việt trong khóa
- khóa dịch lồng nhau
- quản lý chuỗi dịch trong dự án
- i18n cho react
- namespace file dịch
- công cụ hỗ trợ localization
- sinh file ngôn ngữ tự động
