Add textlint CI to enforce Japanese translation style guide

[jp-knj]

Summary

Maintain manual Japanese reviews is becoming increasingly time-consuming.
We propose adding textlint to automatically enforce the existing
Japanese Translation Guide.

Motivation

• Review bandwidth is limited; >30% of JP PRs require style fixes.
• Our style guide already defines deterministic rules (敬体, no spaces between CJK & ASCII, terminology table, …).

Proposed solution

1. Add textlint with the following initial rule set:
   • textlint-rule-preset-jtf-style
   • textlint-rule-prh with a custom dictionary generated from our terminology table
   • textlint-rule-ja-no-space-between-half-and-full-width
2. Run it in CI for src/content/**/ja/**/*.md{,x} only.
3. Fail the job on violations; provide yarn lint:text --fix for contributors.

name: textlint
on:
  pull_request:
    paths:
      - "src/content/**/ja/**.md*"
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with: { version: "latest" }
      - run: pnpm install --frozen-lockfile
      - run: pnpm textlint --format checkstyle "src/content/**/ja/**.md*"

Prior art

• nextjs-ja-translation/Nextjs-ja-translation-docs enforces textlint at
  pre-commit and CI levels (linked below).
  https://github.com/Nextjs-ja-translation/Nextjs-ja-translation-docs/blob/master/README.md?utm_source=chatgpt.com

Open questions

• Should we gate merges on textlint errors immediately or start with warnings?
• Where to keep the prh dictionary (monorepo or sub-package)?

Feedback welcome!

[sarah11918]

Thank you for starting this discussion! I will ask @yanthomasdev @delucis and @TheOtterlord if they have opinions about this!

[jp-knj]

Give you example 🙏🏿 : #11691

[delucis]

Thanks for the suggestion @jp-knj and for the example PR — that’s very helpful to see what would be involved.

I think whether or not we want to do something like this depends on how helpful it will be to the impacted people, which I guess is primarily our Japanese and Chinese translators looking at the PR. I’d love to gather more feedback from them initially to hear what they think and if they think this would help them.

Should we gate merges on textlint errors immediately or start with warnings?

Does textlint only check clear cases? Or can it sometimes generate false negatives? In general we follow a couple of rules re: linting/CI checks:

• If a failing check can be automatically fixed, we should prefer that. (For example, we auto-format code after merging PRs rather than failing a PR and telling people to fix it before merging.)

• If something is worth reporting, it should be an error and fail the PR. Warnings usually get ignored, pile up over time, etc. So we usually think of checks as: if it’s important enough to check, it should fail a PR (assuming it can’t be autofixed like in the first point); and if it’s not important enough to fail a PR, it’s not important enough to check 😁

So assuming textlint would fit into our processes, we would likely need to fix any existing errors from the start and then enforce it going forward.

[jp-knj]

Thanks again!
First, I’m just trying to start with a minimal setup to explore the idea. I'm going to delete PR I've already created.

Then, I plan to apply it to the Japanese version only for now and won’t add it to CI at this point. Depending on the feedback we get, I’m totally fine with dropping the approach if it doesn’t seem helpful.

[sarah11918]

Just checking in on this discussion here, since there is an open PR for this, too. @delucis , I'm not sure whether your concerns have been addressed, and whether anyone else e.g. @yanthomasdev may want to comment on how this might affect our i18n PRs!

[delucis]

As I mentioned above, it would be good to have feedback from the people this is proposing to help. Without input from other impacted translators, it’s quite hard to judge whether adding the extra system will be helpful or not.

[jp-knj]

Hi, I got what you’re saying.
We’ve only received 👍 reactions on PRs [#11812] and [#11691], but no direct comments yet.

For reference, other OSS translation communities already rely on textlint. the Vue.js Japanese team even maintains its own ruleset. https://github.com/vuejs-jp/textlint-rule-preset-vuejs-jp

When I’m translating into Japanese, I personally find it extremely helpful. I hope other supporters and Japanese speakers will share their comments.

[delucis]

I posted a request in our Japanese & Chinese translator threads on Discord to hopefully encourage people to provide some feedback. Thanks for your patience @jp-knj!

[liruifengv]

Hello, I have carefully read your proposal and PR.

I noticed that you used the textlint-rule-preset-ja-spacing preset in your PR, but for Simplified Chinese, I couldn't find a maintained preset package.

In the Vue Chinese docs, they use zhlint to maintain spaces between Chinese and English.

So, if we add textlint, we would need to maintain our own preset rules, which might require a lot of upfront work.

And as Chris said, we may need to fix all existing errors from the beginning and strictly enforce them in subsequent work, which also requires a lot of work handling and verification.

For the current state of the Chinese docs, I believe the benefits it brings are not enough to excite me

[jp-knj]

Thanks for flagging those simplified Chinese concerns.

I thought My current proposal scopes Textlint to src/content/ja/only, so Chinese files and CI are untouched for now. (but my PR title and poc pr? made you misunderstand. So sorry)

the CN team later wants linting, we could "add zhlint—which Vue-CN already uses".

Let me know if limiting the job to JP in this way addresses your worries

I’m heading out now, so I’ll leave a comment once I’m back home later.

[ryuapp]

Thanks for your active contributions to astro docs.

I don't currently contribute much to the docs, but one thing that bothers me in many of the reviews is the inconsistency in terminology. It's a hassle to check the official terms in the glossary, so it seems like a good idea to have textlint suppress spelling inconsistencies.

I think that is very useful because of japanese words are not matched, the search will not work properly.
It's also great that it checks for spaces.

[vrabe]

It's better to use different linters for Japanese and Chinese because textlint's rules are more for Japanese.

If Japanese contributors see textlint as useful, I have no reasons to oppose it using for Japanese linting.

@jp-knj have stated "I plan to apply it to the Japanese version only for now". I don't know why we want Chinese translators' opinions.

[ArmandPhilippot]

To answer you question, I guess because the first PR (#11691) description wasn't clear enough:

This PR introduces textlint to enforce consistent writing style and terminology for localized documentation in:
🇯🇵 Japanese (ja)
🇨🇳 Simplified Chinese (zh-cn)

From my understanding, this implies changes for Chinese translators as well. Maybe jp-knj meant the same thing could be done for Chinese translators too if needed without knowing the implications. And since most of us do no speak Japanese or Chinese, it seemed better to not make any assumption and to ask you for your opinion on this!

From the feedbacks, it seems it could be interesting for Japanese translators, but not the others! So, thank you for your feedback!