How do you translate lychee CLI documentation and broken-link reports without changing the URLs, status codes or commands that people need to investigate? This lychee CLI localization guide explains local Markdown and HTML link checks, remote website scans, HTTP status interpretation, redirects, rate limits, caching, `.lycheeignore`, configuration, CI workflows and Unicode URL quality assurance. It is written for translators, technical writers, documentation engineers and global website maintainers.
lychee is a link checker: it extracts links from supported inputs and tests their reachability according to configured behavior. It does not translate a document, prove a target page contains the intended information or decide whether a medical or legal resource is authoritative. A returned error may describe a broken link, blocked network access, an authenticated page, a rate-limiting response or a configuration problem. Accurate localization preserves those distinctions instead of calling every failure ‘page not found’.
Start with the exact command, checked files and the report’s original URLs and HTTP statuses. Preserve `lychee`, flags such as `–cache`, `–exclude` and `–offline`, literal hostnames, paths, percent-encoded characters, status codes and regex patterns. Translate human-facing explanations and next steps. Then test Unicode paths, internationalized domains, fragment links, redirects, `mailto:` addresses and copied commands in the target language, because visually similar links can lead to different resources.
Quick reference: essential decisions
- Record which files and URLs were included in a link-check run.
- Classify HTTP failure, network timeout, redirect and local-file errors separately.
- Do not translate or ‘pretty up’ raw URLs, headers, regex patterns or CLI flags.
- Use caches and exclusions deliberately; document what they omit from each report.
- Retest unstable or authenticated links before removing them from documentation.
- Treat link reachability as one layer, not proof of factual relevance or translation accuracy.
This guide focuses on link integrity and the interpretation of lychee CLI diagnostics. It does not replace markdownlint-cli2 for Markdown structure, CSpell for spelling or a professional language reviewer for source-to-target equivalence. Its usefulness is strongest when the report keeps exact URLs and checked scope visible.
A safe start-to-finish workflow
Use a small Markdown file with one working local link, one intentionally invalid destination and one external URL that the team controls. Run lychee against the file from the intended working directory and record the exact version and command. Avoid experimenting with sensitive credentials or private network targets in public pipelines. To explore input extraction without making requests, consult the documented `–dump` behavior for the installed release.
Begin in a working copy rather than on irreplaceable published material. Record the installed tool version, command invocation, active configuration, working directory and the file subset that should be checked. Classify every token as user-facing explanation, machine-readable syntax, source evidence or an external reference. That simple inventory prevents the same translation from improving readability while breaking a terminal example.
What link checking actually establishes
lychee extracts URLs from supported inputs and checks whether they are reachable under the chosen request policy. That is useful evidence about access, not the destination’s content accuracy. A linter answers a bounded question about supplied inputs and rules. It is not a substitute for deciding whether the content is accurate, understandable or faithful to its source.
Worked example. A translation team gets a successful link check and claims the linked government regulation still has the same legal meaning. Reproduce the example in a disposable copy, then compare its before and after states. A known failing fixture is often more informative than a completely clean run.
Why it can go wrong. A reachable website can redirect, change content or cease to be the appropriate authority for the paragraph. Avoid translating status words into stronger claims than the tool can support. ‘Detected’, ‘not checked’, ‘ignored’ and ‘corrected’ are different outcomes.
How to verify. Open the important destination and confirm it answers the reader’s actual question. Verify the precise input, the active rule and the expected observable output. Include the reproduction command in the guide when it is safe and useful.
Choose local files or remote sites
lychee can process local documentation and, with supported usage, remote resources. The source of the link inventory is part of the meaning of the report. A good localized guide tells readers what the command did, which policy was applied and how a finding can be reproduced. Those details make the prose genuinely actionable.
Worked example. A translated tutorial describes a local README scan as a complete crawl of the organization’s public website. Ask a new contributor to perform the step using only the localized instructions. If the contributor cannot find the relevant setting, the explanation needs improvement.
Why it can go wrong. Checking one file and crawling a site are different operations with different coverage and consequences. A false positive can justify a narrow exception, but it does not justify dropping the entire quality gate. Record the reason and the affected scope.
How to verify. List exact input paths or site targets, then compare the inventory with expected content. Check both a positive and a negative fixture with the intended configuration. The negative case reveals whether the proposed exception became too permissive.
Understand extraction before requests
Input parsing determines which links lychee finds before any HTTP test occurs. Use available extraction or dump modes to inspect coverage. The first distinction is between literal machine tokens and human explanation. Preserve the former in copyable samples and translate the latter with the reader’s task in mind.
Worked example. A maintainer assumes links inside unsupported generated content were checked because the CLI returned successfully. Look at the observed inputs before interpreting the output. This prevents a change in file selection from being mistaken for a change in document quality.
Why it can go wrong. The success of the request stage cannot prove that every intended link was extracted. Do not convert a readability preference into a factual claim. Automated style conformity and subject-matter correctness remain independent.
How to verify. Inspect the extracted list and compare it with representative Markdown and HTML fixtures. Review any automatic edit as a textual diff, and rerun the relevant checks. A passing command is not evidence that meaning stayed unchanged.
Preserve command tokens
Flags such as `–cache`, `–exclude` and `–offline` are executable syntax. Their plain-language explanations can be localized without changing the tokens. Document the condition behind the result rather than asserting a universal standard. The same source file may produce different results under a different configuration or version.
Worked example. A translated FAQ replaces `–exclude` with a native-language adjective inside a shell sample. Use consistent terminology across a help page, terminal example and review comment. An unfamiliar synonym may cause someone to change an unrelated setting.
Why it can go wrong. A copyable instruction that no longer runs defeats the purpose of the translation. Typographic substitutions in commands, file paths and URLs can create invisible failures. Test copied examples, not only screenshots.
How to verify. Paste the exact command from the localized page into a safe test environment. Check Unicode normalization and rendered direction when mixed scripts are involved. A visually identical string may not be byte-identical.
Read HTTP status codes precisely
HTTP statuses communicate different conditions: a missing page, a server error, a redirect or a request rate limit do not justify the same editorial action. Readers should be able to identify who owns an exception and why it exists. Without that context, apparently harmless changes can undermine an established review policy.
Worked example. A report returns 429 and the localized troubleshooting guide says the link has permanently disappeared. Retain one expected pass and one expected failure in tests. Together they protect a rule against becoming unexpectedly broader or narrower.
Why it can go wrong. Rate limiting may be temporary and unrelated to whether the target resource exists. The absence of an alert can mean the file was excluded or an intended rule never ran. Always check coverage before announcing success.
How to verify. Check the status category, retry responsibly and verify with the source publisher before replacing a link. Preserve a readable audit trail of accepted warnings, affected paths and approving reviewers. That record makes later cleanup easier.
Do not conflate timeout and 404
A timeout is a failure to complete a request under given conditions, whereas 404 means a server reported a missing resource at the requested address. A useful diagnostic includes evidence, interpretation and a next step. It should avoid implying that one machine warning settles a complex editorial decision.
Worked example. A network-restricted CI runner times out on a resource available from the team’s browser. When behavior differs, compare tool versions, working directories and configuration roots before rewriting prose. Environment differences are not automatically translation defects.
Why it can go wrong. Calling a timeout ‘not found’ directs editors to delete valid references. A program’s output can be machine-readable evidence, even when it contains English words. Do not translate fields that downstream parsers expect literally.
How to verify. Record environment, timeout policy and a responsible retry before classifying the URL. Test the result on the target platform and shell rather than extrapolating from a different environment’s command line.
Explain redirects
A redirect can send a link to a new resource, language selector or authentication route. A final reachable page may still be irrelevant to the original citation. Prefer a small reproducible scenario to a long list of unexplained flags. A correct example can reveal precisely which part of the workflow matters.
Worked example. A translated documentation link to one API version redirects to a generic product homepage and the report is treated as a complete success. Make the consequence of each suggested action explicit. Readers should know whether it changes source text, alters a policy, or merely changes reporting.
Why it can go wrong. Connectivity through redirection is not proof of topic continuity or version compatibility. A locally sensible correction may be globally harmful when applied throughout a multilingual repository. Make the intended scope explicit.
How to verify. Inspect the final destination and update the reference when a canonical replacement is known. Keep source filenames, line references and identifiers exact so another reviewer can locate the same evidence.
Respect redirect limits
The checker can apply redirect-following limits. Excessive redirects may indicate a loop or site configuration problem rather than a writing error. Treat inclusion and exclusion as measurable scope. A successful command says nothing about files that were never checked.
Worked example. A link fails after several redirects and the translator rewrites its label instead of investigating the HTTP chain. Check whether a displayed identifier is intended for searching, copying or reading. Each use calls for a different localization decision.
Why it can go wrong. Changing visible text does not repair a redirect loop. Do not mistake a transient infrastructure failure for a defect in the translation. Classify the outcome before prescribing an editorial repair.
How to verify. Trace the chain and identify the authoritative intended destination. Retest after changing configuration. Otherwise a report may reflect a previous selection of files or rules.
Use the HTTP method thoughtfully
Some servers respond differently to HEAD and GET requests, and link checkers may offer request-method behavior. Troubleshooting should consult the installed tool’s options. A linter answers a bounded question about supplied inputs and rules. It is not a substitute for deciding whether the content is accurate, understandable or faithful to its source.
Worked example. A server rejects a lightweight request while an actual browser page loads normally. Reproduce the example in a disposable copy, then compare its before and after states. A known failing fixture is often more informative than a completely clean run.
Why it can go wrong. A rejected method can produce a false impression of broken content. Avoid translating status words into stronger claims than the tool can support. ‘Detected’, ‘not checked’, ‘ignored’ and ‘corrected’ are different outcomes.
How to verify. Compare permitted request behavior safely and record any method-specific exception. Verify the precise input, the active rule and the expected observable output. Include the reproduction command in the guide when it is safe and useful.
Apply retry and concurrency controls
Large checks can stress remote servers. Concurrency and retry settings help keep checks manageable but do not guarantee universal accessibility. A good localized guide tells readers what the command did, which policy was applied and how a finding can be reproduced. Those details make the prose genuinely actionable.
Worked example. A team aggressively scans thousands of links and receives bursts of 429 responses, then marks every domain as broken. Ask a new contributor to perform the step using only the localized instructions. If the contributor cannot find the relevant setting, the explanation needs improvement.
Why it can go wrong. The checker can create the rate-limit condition it is attempting to diagnose. A false positive can justify a narrow exception, but it does not justify dropping the entire quality gate. Record the reason and the affected scope.
How to verify. Reduce concurrency, respect host limits and retry selected links on a reasonable schedule. Check both a positive and a negative fixture with the intended configuration. The negative case reveals whether the proposed exception became too permissive.
Interpret 429 rate limiting
A 429 response typically signals too many requests under the server’s policy. It is not the same as a permanent content removal. The first distinction is between literal machine tokens and human explanation. Preserve the former in copyable samples and translate the latter with the reader’s task in mind.
Worked example. A contributor mass-replaces valid documentation links after a high-volume CI job hits an API limit. Look at the observed inputs before interpreting the output. This prevents a change in file selection from being mistaken for a change in document quality.
Why it can go wrong. Automated deletion could remove valuable references and create needless translation churn. Do not convert a readability preference into a factual claim. Automated style conformity and subject-matter correctness remain independent.
How to verify. Retest under the server’s acceptable usage limits and consult any published rate-limit guidance. Review any automatic edit as a textual diff, and rerun the relevant checks. A passing command is not evidence that meaning stayed unchanged.
Use caching deliberately
lychee supports caching responses to avoid unnecessary repeated network checks. Cached results reflect prior conditions and need appropriate freshness policies. Document the condition behind the result rather than asserting a universal standard. The same source file may produce different results under a different configuration or version.
Worked example. A site undergoes a migration but a job reports old cached successes without checking the new URLs. Use consistent terminology across a help page, terminal example and review comment. An unfamiliar synonym may cause someone to change an unrelated setting.
Why it can go wrong. A cache can improve speed while obscuring recent changes if readers treat results as live. Typographic substitutions in commands, file paths and URLs can create invisible failures. Test copied examples, not only screenshots.
How to verify. Inspect cache settings and run a fresh check when publication or migration requires current confirmation. Check Unicode normalization and rendered direction when mixed scripts are involved. A visually identical string may not be byte-identical.
Exclude unstable statuses from cache
Status exclusion settings can prevent selected responses, such as temporary rate-limit outcomes, from being cached. This is a diagnostic policy choice. Readers should be able to identify who owns an exception and why it exists. Without that context, apparently harmless changes can undermine an established review policy.
Worked example. A 429 response is retained long enough to mislead later editors about a link that now works. Retain one expected pass and one expected failure in tests. Together they protect a rule against becoming unexpectedly broader or narrower.
Why it can go wrong. Storing a transient failure can compound a temporary problem. The absence of an alert can mean the file was excluded or an intended rule never ran. Always check coverage before announcing success.
How to verify. Use the documented cache exclusion configuration and verify that a retry reaches the server. Preserve a readable audit trail of accepted warnings, affected paths and approving reviewers. That record makes later cleanup easier.
Read `.lycheeignore` as policy
Ignore patterns can remove links from a check. Such exclusions should be narrow and justified, not a way to make a warning disappear. A useful diagnostic includes evidence, interpretation and a next step. It should avoid implying that one machine warning settles a complex editorial decision.
Worked example. An editor ignores an entire official documentation domain because some pages require authentication. When behavior differs, compare tool versions, working directories and configuration roots before rewriting prose. Environment differences are not automatically translation defects.
Why it can go wrong. The visible report can turn green while skipping vital citations. A program’s output can be machine-readable evidence, even when it contains English words. Do not translate fields that downstream parsers expect literally.
How to verify. Review each pattern and include a reason, owner and periodic recheck date. Test the result on the target platform and shell rather than extrapolating from a different environment’s command line.
Separate path and URL exclusions
Excluding a file path is different from excluding destination URLs. Translators should explain which side of the workflow a flag affects. Prefer a small reproducible scenario to a long list of unexplained flags. A correct example can reveal precisely which part of the workflow matters.
Worked example. A team excludes a generated directory but thinks it has blocked requests to a private domain embedded in another file. Make the consequence of each suggested action explicit. Readers should know whether it changes source text, alters a policy, or merely changes reporting.
Why it can go wrong. A mistaken scope can have both privacy and reporting consequences. A locally sensible correction may be globally harmful when applied throughout a multilingual repository. Make the intended scope explicit.
How to verify. Test one source file and one destination matching each intended exclusion. Keep source filenames, line references and identifiers exact so another reviewer can locate the same evidence.
Use regex exclusions safely
Regular expressions identify groups of URLs. A broad pattern may match more than the author expects, and translation must never alter its metacharacters casually. Treat inclusion and exclusion as measurable scope. A successful command says nothing about files that were never checked.
Worked example. A localized sample removes escape characters from a regex intended to exclude one host. Check whether a displayed identifier is intended for searching, copying or reading. Each use calls for a different localization decision.
Why it can go wrong. The result may exclude unrelated hosts or fail to exclude the intended one. Do not mistake a transient infrastructure failure for a defect in the translation. Classify the outcome before prescribing an editorial repair.
How to verify. Test the pattern against examples that should match and should not match. Retest after changing configuration. Otherwise a report may reflect a previous selection of files or rules.
Understand offline checks
Offline behavior can prevent network requests while still allowing useful processing of appropriate local references. It must not be advertised as confirmation of external websites. A linter answers a bounded question about supplied inputs and rules. It is not a substitute for deciding whether the content is accurate, understandable or faithful to its source.
Worked example. An isolated CI job runs offline and a release note claims every external page was reachable. Reproduce the example in a disposable copy, then compare its before and after states. A known failing fixture is often more informative than a completely clean run.
Why it can go wrong. The job cannot know whether a remote server is currently responding without a network request. Avoid translating status words into stronger claims than the tool can support. ‘Detected’, ‘not checked’, ‘ignored’ and ‘corrected’ are different outcomes.
How to verify. State which local links were checked and schedule a separate permitted online verification. Verify the precise input, the active rule and the expected observable output. Include the reproduction command in the guide when it is safe and useful.
Check local relative paths
Relative links resolve according to document location and configured root or base behavior. Moving translations into locale folders can break paths. A good localized guide tells readers what the command did, which policy was applied and how a finding can be reproduced. Those details make the prose genuinely actionable.
Worked example. An English guide references `../images/chart.png`; a Spanish copy is moved two directory levels deeper with no link adjustment. Ask a new contributor to perform the step using only the localized instructions. If the contributor cannot find the relevant setting, the explanation needs improvement.
Why it can go wrong. The visible label translates correctly while the actual local resource is missing. A false positive can justify a narrow exception, but it does not justify dropping the entire quality gate. Record the reason and the affected scope.
How to verify. Render and check links from each translated file’s real location. Check both a positive and a negative fixture with the intended configuration. The negative case reveals whether the proposed exception became too permissive.
Handle anchors and fragments
Fragments such as `#installation` often refer to generated heading identifiers or explicit HTML IDs. Their behavior can change when headings are translated. The first distinction is between literal machine tokens and human explanation. Preserve the former in copyable samples and translate the latter with the reader’s task in mind.
Worked example. A French page translates the ‘Installation’ heading but its table of contents still points to the original English slug. Look at the observed inputs before interpreting the output. This prevents a change in file selection from being mistaken for a change in document quality.
Why it can go wrong. A reachable page may still fail to land at the intended section. Do not convert a readability preference into a factual claim. Automated style conformity and subject-matter correctness remain independent.
How to verify. Test the anchor with the actual site renderer and its fragment-check policy. Review any automatic edit as a textual diff, and rerun the relevant checks. A passing command is not evidence that meaning stayed unchanged.
Localize labels but not destinations blindly
A link label is written for the reader and is ordinarily translatable. A destination is technical data and may require an approved locale-specific replacement. Document the condition behind the result rather than asserting a universal standard. The same source file may produce different results under a different configuration or version.
Worked example. A translator changes an official security advisory URL to a similar-looking translated slug that does not exist. Use consistent terminology across a help page, terminal example and review comment. An unfamiliar synonym may cause someone to change an unrelated setting.
Why it can go wrong. Guessing localized paths is not the same as choosing an authorized equivalent resource. Typographic substitutions in commands, file paths and URLs can create invisible failures. Test copied examples, not only screenshots.
How to verify. Keep the known working URL or verify the publisher’s official localized destination. Check Unicode normalization and rendered direction when mixed scripts are involved. A visually identical string may not be byte-identical.
Unicode in URL paths
Non-ASCII characters in paths may be percent-encoded for transmission. Visual spelling, byte representation and canonical destination can differ. Readers should be able to identify who owns an exception and why it exists. Without that context, apparently harmless changes can undermine an established review policy.
Worked example. A copied accented path appears readable but its percent escapes have been altered by automatic punctuation replacement. Retain one expected pass and one expected failure in tests. Together they protect a rule against becoming unexpectedly broader or narrower.
Why it can go wrong. A URL that looks similar may identify a different resource or fail entirely. The absence of an alert can mean the file was excluded or an intended rule never ran. Always check coverage before announcing success.
How to verify. Compare raw and copied URLs and test with the intended encoding. Preserve a readable audit trail of accepted warnings, affected paths and approving reviewers. That record makes later cleanup easier.
Internationalized domain names
Some domains use non-Latin scripts and may have ASCII-compatible representations. Translators must preserve the authoritative host, not invent a localized spelling. A useful diagnostic includes evidence, interpretation and a next step. It should avoid implying that one machine warning settles a complex editorial decision.
Worked example. A guide silently changes an internationalized domain to a homograph resembling a legitimate organization. When behavior differs, compare tool versions, working directories and configuration roots before rewriting prose. Environment differences are not automatically translation defects.
Why it can go wrong. A plausible display string can lead readers to a different site, creating security and trust risks. A program’s output can be machine-readable evidence, even when it contains English words. Do not translate fields that downstream parsers expect literally.
How to verify. Compare domains with the publisher’s official source and inspect the actual destination. Test the result on the target platform and shell rather than extrapolating from a different environment’s command line.
Preserve query strings
Queries can carry version identifiers, selected languages or document anchors. Removing them for aesthetic reasons can change which content a reader sees. Prefer a small reproducible scenario to a long list of unexplained flags. A correct example can reveal precisely which part of the workflow matters.
Worked example. An API guide strips a `lang` or version query parameter from a documentation link during localization. Make the consequence of each suggested action explicit. Readers should know whether it changes source text, alters a policy, or merely changes reporting.
Why it can go wrong. The reader may reach the wrong locale or an outdated reference. A locally sensible correction may be globally harmful when applied throughout a multilingual repository. Make the intended scope explicit.
How to verify. Test the intended variant and preserve supported parameter encoding. Keep source filenames, line references and identifiers exact so another reviewer can locate the same evidence.
Handle email addresses carefully
A `mailto:` link and an HTTP URL have different behaviors and privacy implications. A checker may offer separate controls for email address checks. Treat inclusion and exclusion as measurable scope. A successful command says nothing about files that were never checked.
Worked example. A localized contact guide turns a real support mailbox into an invented translated domain. Check whether a displayed identifier is intended for searching, copying or reading. Each use calls for a different localization decision.
Why it can go wrong. A human-readable address can be undeliverable even if the prose is fluent. Do not mistake a transient infrastructure failure for a defect in the translation. Classify the outcome before prescribing an editorial repair.
How to verify. Verify authorized contact details and do not send test messages to third parties without permission. Retest after changing configuration. Otherwise a report may reflect a previous selection of files or rules.
Protect authorization and private networks
Some resources require credentials, cookies or headers. Such inputs must be treated as secrets, and scanners should not probe private infrastructure indiscriminately. A linter answers a bounded question about supplied inputs and rules. It is not a substitute for deciding whether the content is accurate, understandable or faithful to its source.
Worked example. A public tutorial embeds an access token in a copyable link-check command so readers can reproduce an authenticated result. Reproduce the example in a disposable copy, then compare its before and after states. A known failing fixture is often more informative than a completely clean run.
Why it can go wrong. A documentation example can leak credentials or encourage unsafe network probing. Avoid translating status words into stronger claims than the tool can support. ‘Detected’, ‘not checked’, ‘ignored’ and ‘corrected’ are different outcomes.
How to verify. Use sanitized examples, protected CI secrets and a reviewed scope for privileged checks. Verify the precise input, the active rule and the expected observable output. Include the reproduction command in the guide when it is safe and useful.
Use configuration consistently
The `lychee.toml` file and CLI settings can define a repeatable policy. A guide should state whether a value is coming from the file or the command line. A good localized guide tells readers what the command did, which policy was applied and how a finding can be reproduced. Those details make the prose genuinely actionable.
Worked example. A maintainer edits a sample config but a job overrides it with a CLI flag, so the translated instructions appear ineffective. Ask a new contributor to perform the step using only the localized instructions. If the contributor cannot find the relevant setting, the explanation needs improvement.
Why it can go wrong. Troubleshooting is impossible when effective settings are not documented. A false positive can justify a narrow exception, but it does not justify dropping the entire quality gate. Record the reason and the affected scope.
How to verify. Record the command and loaded configuration, then test one deliberately excluded and one included link. Check both a positive and a negative fixture with the intended configuration. The negative case reveals whether the proposed exception became too permissive.
Understand exit codes in CI
The checker distinguishes successful checks, link failures and configuration or execution errors through exit statuses defined in its documentation. They should not all be called broken links. The first distinction is between literal machine tokens and human explanation. Preserve the former in copyable samples and translate the latter with the reader’s task in mind.
Worked example. An invalid TOML file causes CI to fail and the automated translation says ten websites are unavailable. Look at the observed inputs before interpreting the output. This prevents a change in file selection from being mistaken for a change in document quality.
Why it can go wrong. The problem is a malformed policy file, not ten confirmed destination failures. Do not convert a readability preference into a factual claim. Automated style conformity and subject-matter correctness remain independent.
How to verify. Inspect the exact exit code and stderr before advising a contributor to replace any URL. Review any automatic edit as a textual diff, and rerun the relevant checks. A passing command is not evidence that meaning stayed unchanged.
Generate useful reports
A readable report should preserve source file, destination, status and check context. Human translation may explain the status but should not rewrite evidence fields. Document the condition behind the result rather than asserting a universal standard. The same source file may produce different results under a different configuration or version.
Worked example. An editor translates a destination URL and drops its source filename from a problem summary. Use consistent terminology across a help page, terminal example and review comment. An unfamiliar synonym may cause someone to change an unrelated setting.
Why it can go wrong. The next contributor cannot find or reproduce the result from the summary alone. Typographic substitutions in commands, file paths and URLs can create invisible failures. Test copied examples, not only screenshots.
How to verify. Keep raw machine evidence intact and provide an adjacent human-readable explanation. Check Unicode normalization and rendered direction when mixed scripts are involved. A visually identical string may not be byte-identical.
Document temporary exceptions
Temporary hosting incidents, rate limiting or authentication barriers may justify deferred rechecks. They should never become unexplained permanent exclusions. Readers should be able to identify who owns an exception and why it exists. Without that context, apparently harmless changes can undermine an established review policy.
Worked example. A team ignores a flaky documentation domain and forgets about it for months, while key readers keep encountering failures. Retain one expected pass and one expected failure in tests. Together they protect a rule against becoming unexpectedly broader or narrower.
Why it can go wrong. A passing badge then reflects policy gaps rather than healthy references. The absence of an alert can mean the file was excluded or an intended rule never ran. Always check coverage before announcing success.
How to verify. Assign an owner and review date to exceptions and rerun a fresh check after the incident. Preserve a readable audit trail of accepted warnings, affected paths and approving reviewers. That record makes later cleanup easier.
Test multilingual release pages
Each translated page may have different local paths, fragment identifiers and destination locales. A single English link run cannot establish integrity everywhere. A useful diagnostic includes evidence, interpretation and a next step. It should avoid implying that one machine warning settles a complex editorial decision.
Worked example. A Japanese translation uses a localized heading fragment that the English build never checked. When behavior differs, compare tool versions, working directories and configuration roots before rewriting prose. Environment differences are not automatically translation defects.
Why it can go wrong. A global publishing claim can conceal locale-specific broken navigation. A program’s output can be machine-readable evidence, even when it contains English words. Do not translate fields that downstream parsers expect literally.
How to verify. Run representative checks per locale and inspect important destinations in context. Test the result on the target platform and shell rather than extrapolating from a different environment’s command line.
Separate reachability from trust and meaning
A response that loads successfully may be obsolete, misleading, redirected to advertising or wrong for the cited claim. Link quality requires editorial judgment. Prefer a small reproducible scenario to a long list of unexplained flags. A correct example can reveal precisely which part of the workflow matters.
Worked example. A published medical explainer links to an accessible page that now discusses an unrelated treatment. Make the consequence of each suggested action explicit. Readers should know whether it changes source text, alters a policy, or merely changes reporting.
Why it can go wrong. An HTTP success should not be narrated as a verified expert source. A locally sensible correction may be globally harmful when applied throughout a multilingual repository. Make the intended scope explicit.
How to verify. Open significant references, evaluate authority and check that their content still supports the sentence. Keep source filenames, line references and identifiers exact so another reviewer can locate the same evidence.
One complete editorial case study
Imagine a product-docs site translated into English, German, Japanese and Arabic. Each locale has Markdown files and translated heading anchors. The team runs lychee on the source tree, explicitly including locale directories. It first verifies input extraction, then records which destinations were queried. Links to private developer environments are excluded by a documented rule rather than being accidentally exposed to a public check.
The first result is a 404 from an outdated API endpoint: the owner finds the current canonical versioned path and confirms that its content explains the same behavior. A second result is 429 after excessive concurrent requests. That link is not deleted. The team reduces request pressure, retests responsibly and configures the cache so a temporary rate-limit response is not treated as a long-lived verdict.
Meanwhile, the Japanese guide contains a heading with Unicode characters and an anchor copied from the English page. The source page is accessible, but the fragment does not identify the intended section. The reviewer checks the rendered Japanese page and repairs the anchor. In the Arabic guide, commands remain left-to-right tokens even when surrounded by right-to-left prose; raw code points and copied URLs are verified.
The release summary distinguishes confirmed dead links, temporary server errors, authenticated resources and unresolved content-quality decisions. It names exceptions, owners and recheck requirements. Most importantly, it does not equate a reachable link with a verified citation. Someone still opens the important destinations and decides whether they support the claims for readers in each language.
Frequently asked questions
Does lychee translate website content or check factual accuracy?
No. It extracts and checks links under the configured network and file rules. A reachable page can still be outdated, untrustworthy or unrelated to the translated claim.
Does HTTP 429 mean a link is broken permanently?
No. It usually indicates a rate-limit response. Reduce request pressure, follow publisher guidance and retry responsibly before deciding that a reference should be replaced.
Should I translate raw URLs or status codes?
No. Keep raw addresses, encoding, query strings, HTTP codes, headers and command flags exact. Translate adjacent human explanations and use an official verified locale-specific URL only when a real alternative exists.
Can I use cache results as live availability proof?
Cached results describe earlier checks. They are useful for performance, but a migration or release may require a fresh network request under suitable conditions.
Why does the source page open but the fragment link fail?
The heading anchor may differ across Markdown renderers or translated pages. Test the actual rendered target, not only the base URL, and ensure the fragment identifies the intended section.
What makes a CI link report trustworthy?
A trustworthy report states checked inputs, exceptions, configured network behavior and distinct failure categories. It preserves raw evidence and includes human review for content relevance, trust and meaning.
Final checklist
- Preserve literal URLs, flags, status codes, regex and configuration keys.
- Identify all checked source files and extracted destinations.
- Separate 404, timeout, redirects, rate limits and configuration errors.
- Review cache, exclusion, private-network and credential handling.
- Test locale-specific paths, fragments and Unicode addresses.
- Verify that important reachable pages still support their claims.