Skip to content

You're viewing the prerelease documentation siteContent here is for testing and may differ from the live docs.

Go to live docs
Onetime SecretOnetime Secret - Docsdocs

Translation Quality Checklist

This checklist helps ensure translations meet Onetime Secret’s quality standards before submission. Use this as a guide when translating documentation or reviewing translation contributions.

Pre-Translation Planning

Section titled “Pre-Translation Planning”

Before starting your translation:

Core Quality Criteria

Section titled “Core Quality Criteria”

1. Completeness ✅

Section titled “1. Completeness ✅”
  • All source content sections are translated (no missing paragraphs)
  • All headings and subheadings are translated
  • All list items are translated
  • Frontmatter (title, description) is translated
  • Code comments are translated where appropriate
  • No English text remains except:
    • Technical terms (API, URL, DNS, SSL, HTTP, JSON, etc.)
    • Code examples and command-line syntax
    • Brand names (Onetime Secret, GitHub, etc.)

2. Formality Consistency ✅

Section titled “2. Formality Consistency ✅”
  • Consistent use of formal/informal address throughout
    • German: Use “Sie/Ihre” (formal) consistently
    • French: Use “vous/votre” (formal) consistently
    • Spanish: Use “usted/su” (formal) consistently
    • Check your language’s conventions in the style guide
  • No mixing of formality levels within same document
  • Address matches target audience (professional B2B users)
  • Tone is professional but approachable

3. Terminology Standards ✅

Section titled “3. Terminology Standards ✅”
  • Core terms match the Glossary:
    • secret → (check glossary for your language)
    • passphrase → (check glossary - must differ from “password”)
    • password → (check glossary - must differ from “passphrase”)
    • burn → (check glossary)
    • one-time → (check glossary)
  • Technical security terms are accurate and consistent
  • UI element names match the locale’s i18n.json file
  • Brand terms are not translated:
    • Onetime Secret (not translated)
    • OTS (not translated when used as product abbreviation)
    • Product names: Identity Plus, Global Elite, Custom Install

4. Link Localization ✅

Section titled “4. Link Localization ✅”
  • All internal documentation links use locale prefix:
    • ✅ Correct: [Guide](/fr/translations/guide)
    • ❌ Wrong: [Guide](/en/translations/guide)
    • ❌ Wrong: [Guide](translations/guide)
  • Link text is translated appropriately
  • External links remain in English (unless linking to localized external content)
  • Anchor links are updated if heading text changed
  • All links tested and working

5. Markdown Formatting ✅

Section titled “5. Markdown Formatting ✅”
  • No malformed markdown syntax:
    • Links: [text](url) format correct
    • Bold: **text** wraps the text properly
    • Italics: *text* or _text_ wraps properly
    • Code: `code` inline, ```language for blocks
  • Headings use proper hierarchy (H1 → H2 → H3)
  • Lists use consistent markers (-, *, or numbered)
  • Tables are properly formatted with aligned columns
  • Line breaks and spacing match source document

6. File Structure ✅

Section titled “6. File Structure ✅”
  • File placed in correct locale directory (e.g., /content/docs/fr/)
  • Filename matches English source exactly
  • Directory structure mirrors English version
  • File encoding is UTF-8
  • Line endings are consistent (LF preferred)
  • Frontmatter YAML is valid and complete

7. Cultural Adaptation ✅

Section titled “7. Cultural Adaptation ✅”
  • Examples are culturally appropriate
  • Date formats match locale conventions (if applicable)
  • Number formats match locale (decimal separators, thousands)
  • Currency symbols are appropriate
  • Measurements use locale-standard units
  • Time formats match locale (12h vs 24h)
  • Regional variants respected (e.g., fr-FR vs fr-CA)

8. Natural Language Quality ✅

Section titled “8. Natural Language Quality ✅”
  • Translation sounds natural, not machine-translated
  • Grammar is correct for target language
  • Punctuation follows target language conventions
  • Sentence structure is idiomatic
  • No literal word-for-word translations that sound awkward
  • Technical accuracy maintained while sounding natural
  • Spelling is correct (including diacritics/accents)

Post-Translation Review

Section titled “Post-Translation Review”

Self-Review

Section titled “Self-Review”
  • Read entire translation aloud to check flow
  • Compare side-by-side with English to ensure nothing missed
  • Check all links by clicking through them
  • Verify code blocks render correctly
  • Test in local development environment if possible
  • Run spell checker for target language
Section titled “Peer Review (Recommended)”
  • Have another native speaker review translation
  • Get feedback on terminology choices
  • Verify formality level is appropriate
  • Confirm cultural adaptations make sense

Technical Validation

Section titled “Technical Validation”
  • Markdown renders correctly (no broken formatting)
  • Images display with translated alt text
  • Tables are readable and properly aligned
  • Code examples work (if translatable portions were changed)
  • No broken links or 404 errors

Accessibility Considerations

Section titled “Accessibility Considerations”
  • Image alt text is translated
  • Link text is descriptive (not just “click here”)
  • Heading hierarchy is logical for screen readers
  • Tables have proper header cells
  • Language attributes set correctly if using HTML

Submission Checklist

Section titled “Submission Checklist”

Before creating your pull request:

  • All files committed to correct branch
  • Commit message follows format: [i18n] Add [language] translation for [section]
  • Changes tested locally (if possible)
  • PR description explains what was translated
  • Referenced any related issues
  • Requested review from language-specific reviewers (if known)

Quick Reference

Section titled “Quick Reference”

Common Issues to Avoid

Section titled “Common Issues to Avoid”

❌ Don’t:

  • Mix formal and informal address
  • Translate brand names
  • Leave links without locale prefix
  • Use machine translation without review
  • Translate technical acronyms (API, DNS, etc.)
  • Copy-paste English when stuck (ask for help instead)

✅ Do:

  • Follow glossary for core terms
  • Maintain professional tone
  • Test all links
  • Ask questions in GitHub issues
  • Provide context in PR descriptions
  • Review your own work before submitting

Getting Help

Section titled “Getting Help”

If you’re unsure about any aspect of translation:

  1. Check the Translation Style Guide
  2. Review the Terminology Glossary
  3. Look at existing translations in your language for examples
  4. Ask in GitHub issues or discussions
  5. Tag language-specific reviewers if known
  6. Contact the team for clarification

Quality Grading (Internal Reference)

Section titled “Quality Grading (Internal Reference)”

Based on QA reviews, translations are graded on:

  • Completeness: % of source files translated
  • UI Translation: % of UI strings in i18n.json
  • Content Quality: Grammar, natural phrasing, accuracy
  • Link Localization: % of links properly localized
  • Natural Phrasing: How natural the translation sounds
  • Formatting: Markdown and structure quality

Target grade: A (all criteria met consistently)

Last Updated: 2025-11-18 Maintained by: Onetime Secret Documentation Team