Skip to content

wolfSSL manual (JA): sync the Japanese translation with the English 5.9.4 update - #299

Open
LinuxJedi wants to merge 2 commits into
wolfSSL:masterfrom
LinuxJedi:ja-sync-wolfssl-manual
Open

LinuxJedi wants to merge 2 commits into
wolfSSL:masterfrom
LinuxJedi:ja-sync-wolfssl-manual

Conversation

@LinuxJedi

Copy link
Copy Markdown
Member

Summary

The English wolfSSL manual was heavily revised for wolfSSL 5.9.4: corrected defaults, regrouped macros, many new macros and configure options, new sections, fixed examples and internal links. The Japanese translation in wolfSSL/src-ja had fallen well behind. Before this change, chapter02 alone had about 640 fewer headings than the English.

This PR brings every Japanese chapter and appendix back in line with the current English. Appendices A-C are API placeholders and are unchanged. Each file now has the same headings, code blocks, tables and lists as the English, in the same order. Existing Japanese wording is kept where it still matches the English. New and changed text is translated, and text the English removed is dropped.

There are two commits:

  1. English fixes: errors in wolfSSL/src found while doing the sync (listed below).
  2. Japanese sync: wolfSSL/src-ja only.

The Japanese text needs a careful review by a native speaker, especially the new entries in chapter02 (about 650 macros and options are new or rewritten), chapter04, chapter10, and appendices F, G and I.

Conventions used

  • Macro, configure option and other identifier headings stay in English, so the English anchors work in the Japanese build too.
  • Links to sections whose Japanese heading is in Japanese use the existing form [第N章 ...](chapterNN.md)の「...」節. The English anchor does not exist in the Japanese HTML or PDF.
  • Some API functions are not yet documented in the Japanese API reference (header_files-ja). Links to them are plain inline code, so they don't point nowhere.
  • Code blocks match the English. Where the previous Japanese had translated code comments, the current English code keeps Japanese comments. This covers the PKCS#12 and static memory examples in chapter04, three blocks in chapter02 and one block each in appendices H and K. Only the comment text differs from the English.
  • Japan-specific content is kept: info@wolfssl.jp contacts, wolfssl.jp pages, the tex2e Japanese RFC translation links, the Japanese porting guide link, and the @wolfSSL_Japan X account.
  • No em dashes, smart quotes or full-width ASCII symbols (#, %, & are now plain ASCII). Inline code and code are plain ASCII apart from the translated comments above.

Decisions for the Japan team to check

  • chapter04, static memory: the Japanese-only subsections 「静的バッファ利用状況のトラッキング」, 「静的バッファ管理API」, 「I/O用バッファの設定用マクロ定義」 and 「必要バッファサイズの取得」 are removed. They were written for the Japanese manual (3fb660a) while the English still had placeholders there. The English now has its own sections in that place, and those are translated. Parts of the removed text no longer match the API, for example the wolfSSL_StaticBufferSz semantics, the DTLS method list and the wolfSSL_is_static_memory argument type.
  • chapter15, Competitive Upgrade Program: this section was removed from the Japanese in "remove old price" (f26b46f). It is restored, because the English no longer lists a price. The contact is info@wolfssl.jp. Please remove it again if the program does not apply in Japan.
  • Other Japanese-only text removed, because the English never had it or later removed it:
    • chapter02: the bullet about including wolfssl/wolfcrypt/settings.h in the IDE project steps (63b243b).
    • chapter03: the pointer to the -188 explanation.
    • chapter07: the old CSR limitations section and its info@wolfssl.jp line, which the English replaced with "Using a CSR".
  • appendix10: the English consulting URL stays out, as in 5a4cc15.
  • 「(旧称CyaSSL)」 is back in chapters 05, 08, 09, 12, 13 and 15, matching the English and chapters 03 and 04.
  • appendix G: the table header "Wire ID" is now "Wire Value", as in the English.
  • New terms with no earlier use in src-ja: ブラインディング, 定数時間, 位数, 前方秘匿性, トラストアンカー, 証明書パス, 鍵のロールオーバー証明書, 鍵マテリアルエクスポーター, 電源投入時セルフテスト(POST), 鍵暗号化鍵(KEK), 低消費電力AESモジュール, 物理複製困難関数 (PUF), ペアワイズ整合性テスト, カプセル化解除鍵, メモリハード, and 最小構成 / 追加項目 (the floor and adders in the --enable-tinytls13 section).

Errors in the previous Japanese that are fixed

Besides catching up with the English, some existing translations said something different from the English:

  • chapter02: WOLFSSL_ALT_CERT_CHAINS said the errors are not ignored, the opposite of the English. WOLFSSL_RSA_VERIFY_ONLY had lost "verify only". WOLFSSL_AESNI had the .asm/.S syntax reversed.
  • chapter04 and appendix I: ML-DSA was described as based on Kyber.
  • chapter07: the domain check compared the issuer name instead of the subjectAltName DNS entries, and the *_file/*_buffer sentence was reversed.
  • appendix F: CRYPTGEN_E was translated as encryption rather than generation. The SRP and SKID/AKID rows (-217 to -222) were off by one.
  • Throughout: broken anchors (#debug_wolfSSL, #wolfSSL_rsa_* and others) now use the English lowercase targets.

English fixes (first commit)

  • chapter04: "see Appendix A" for the SSL/TLS/DTLS comparison now points to Appendix D. "Shown in the table above" now points to the Supported Cipher Suites section.
  • chapter02: WOLFSSL_CRYPT_HW_MUTEX now gives the full function names.
  • chapter02: --enable-aeskeywrap now says only the padding variant is new in 5.9.4.
  • chapter02: the RT1170 section now names the right wolfssl-examples directories for the CSR and PKCS7 examples.
  • chapter02, 04 and 11: wolfSSL_CTX_set_ephemeral_key() and the DTLS 1.2 method links pointed at ssl_8h.md. In the English HTML build those anchors are on group__CertsKeys and group__Setup, so the links were broken in HTML (the PDF hid it).
  • chapter03: missing separator in the echoserver command list.
  • chapter07: "i.e." is now "e.g.", and _DerToPem()_ is now wc_DerToPem().
  • chapter11: "so that the when" is now "so that when".

Testing

  • Built the Japanese PDF and HTML and the English PDF and HTML in the repo's Docker builder image.
    • Japanese PDF: 0 LaTeX warnings, down from 50 before this change.
    • Japanese PDF and HTML: 0 broken internal anchors, down from 45 (PDF) and 49 (HTML).
    • English PDF and HTML: 0 warnings and 0 broken internal anchors.
  • Per-file structural check against the English: same heading levels and order, same identifier headings, identical code blocks (apart from the translated comments above), and the same table row counts.
  • codespell with the CI word list passes on wolfSSL/src and wolfSSL/src-ja.

Note: the Docker builder image has no xeCJK, so the Japanese PDF does not build in it as-is. I added tlmgr install xecjk locally to test. CI only builds the English PDF, so this PR doesn't change that.

- chapter02: give the full WOLFSSL_CRYPT_HW_MUTEX lock/unlock function
  names.
- chapter02: --enable-aeskeywrap: only the RFC 5649 padding variant is new
  in 5.9.4, not the whole option.
- chapter02: the wolfssl-examples CSR and PKCS7 examples are in the
  certgen and pkcs7 directories, not cmake.
- chapter02, 04, 11: wolfSSL_CTX_set_ephemeral_key() and the DTLS 1.2
  method functions are documented on the CertsKeys and Setup group pages.
  The ssl.h page has no anchor for them in the HTML build.
- chapter03: add the missing separator after `break` in the echoserver
  command list.
- chapter04: the SSL/TLS/DTLS comparison is in Appendix D, not
  Appendix A, and the cipher suites are lists, not a table.
- chapter07: "i.e." -> "e.g." for the trust peer certificate type, and
  name wc_DerToPem() correctly.
- chapter11: fix "so that the when".
The English manual was revised heavily for wolfSSL 5.9.4, and the
Japanese translation had fallen behind, in places by several releases.
Bring every Japanese chapter and appendix back in line with the current
English: the same headings, code blocks, tables and lists, in the same
order.

- Keep the existing Japanese wording where it still matches the English,
  translate new and changed text, and drop text the English removed.
- Macro and configure option headings stay in English so their anchors
  work in both languages. Links to sections with Japanese headings use
  the existing file link plus section name form.
- Links to API functions that the Japanese API reference does not cover
  yet are plain inline code.
- Code blocks match the English. Blocks whose comments were translated
  before keep Japanese comments on the current code.
- Keep Japan-specific content: info@wolfssl.jp, wolfssl.jp pages, the
  Japanese RFC translation links and the Japanese porting guide link.
- Fix mistranslations, broken anchors, full-width ASCII symbols and
  wolfSSL/wolfssl path casing in the existing text.
Copilot AI balanced review requested due to automatic review settings November 17, 2026 15:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Japan-team confirmation is needed before publishing the restored Competitive Upgrade Program, which promises onsite consulting and a royalty-free license despite its applicability in Japan remaining unresolved.

No open issues 🎉

What changed in this PR

This documentation-only PR brings the Japanese wolfSSL manual into alignment with the English 5.9.4 update, while preserving Japan-specific contacts and resources. It also corrects several English references and explanations.

Changes:

  • Updates Japanese feature, configuration, integration, and troubleshooting guidance for wolfSSL 5.9.4.
  • Refreshes examples, API descriptions, error tables, hardware support, and standards references.
  • Corrects English API links, example locations, and wording.
File Description
wolfSSL/​src/​chapter11.md Fixes a DTLS API link and tutorial wording.
wolfSSL/​src/​chapter07.md Corrects certificate-format wording and the wc_DerToPem() reference.
wolfSSL/​src/​chapter04.md Corrects API links and feature cross-references.
wolfSSL/​src/​chapter03.md Fixes command-list punctuation.
wolfSSL/​src/​chapter02.md Clarifies function names, padding support, and example locations.
wolfSSL/​src-ja/​chapter16.md Updates release-information sources.
wolfSSL/​src-ja/​chapter15.md Adds vulnerability-reporting guidance and refreshes support services.
wolfSSL/​src-ja/​chapter14.md Updates licensing and FIPS information.
wolfSSL/​src-ja/​chapter13.md Refreshes OpenSSL compatibility guidance and examples.
wolfSSL/​src-ja/​chapter12.md Expands signing guidance to modern and post-quantum algorithms.
wolfSSL/​src-ja/​chapter11.md Updates TLS tutorial examples, defaults, and cleanup instructions.
wolfSSL/​src-ja/​chapter09.md Clarifies configuration headers, initialization, threading, and buffers.
wolfSSL/​src-ja/​chapter08.md Expands logging controls and error-handling guidance.
wolfSSL/​src-ja/​chapter06.md Updates callback interfaces and documents additional callback capabilities.
wolfSSL/​src-ja/​chapter05.md Refreshes portability interfaces, platform support, and C# examples.
wolfSSL/​src-ja/​chapter01.md Updates the introductory feature and protocol overview.
wolfSSL/​src-ja/​appendix11.md Clarifies wolfSM setup and adds RISC-V optimization support.
wolfSSL/​src-ja/​appendix10.md Modernizes platform-porting instructions and references.
wolfSSL/​src-ja/​appendix08.md Expands hardware-acceleration tables and corrects activation options.
wolfSSL/​src-ja/​appendix06.md Updates error-code tables and retry guidance.
wolfSSL/​src-ja/​appendix05.md Refreshes cryptographic standards and protocol references.
wolfSSL/​src-ja/​appendix04.md Adds TLS 1.3 handshake and DTLS explanations.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants