OrcaSlicer/AGENTS.md

CLAUDE.md

OrcaSlicer — open-source C++17 3D slicer. wxWidgets GUI, CMake build system.

Build Commands

Build the Release configuration unless asked otherwise.

# macOS
cmake --build build/arm64 --config Release --target all --

# Linux
cmake --build build --config Release --target all --

# Windows
cmake --build . --config Release --target ALL_BUILD -- -m

Testing

Catch2 framework. Tests in tests/; see tests/AGENTS.md for where a new test belongs and the conventions to follow.

cd build && ctest -C Release --output-on-failure    # all tests
ctest --test-dir ./tests/libslic3r -C Release       # individual suite
ctest --test-dir ./tests/fff_print -C Release

Documentation

• Docs live in docs/; the high-level design of a subsystem goes in docs/HLSD/<subsystem>.md.
• Describe the design as it stands — what the subsystem does, why it exists, and the constraints that shape it. Not the route that got there: no phases, task lists, status markers, or "before/after this PR" framing.
• Planning and investigation output (brainstorms, superpowers design and plan docs) stays in docs/superpowers/, which is gitignored. Never commit it.
• Write a doc only when the design is not evident from the code, and when a change invalidates an existing one, update it in the same PR.

Code Style

• C++17, selective C++20. PascalCase classes, snake_case functions/variables
• #pragma once for headers. Smart pointers and RAII preferred
• Include what you use: include the header for every symbol a file uses, and keep headers compilable on their own. Never rely on the precompiled header or a transitive include. The clang-tidy CI job enforces this on changed lines; run the same check locally with scripts/run_clang_tidy.sh (scripts\run_clang_tidy.ps1 on Windows), which sets up everything it needs
• Parallelization via TBB — be mindful of shared state
• Always use SetSizerAndFit(sizer) instead of SetSizer(sizer) on top level window. Unless SetSizer must be called before the full layout is built, call sizer->SetSizeHints(window) afterwards in this case.

Key Entry Points

• App startup: src/OrcaSlicer.cpp
• Slicing pipeline: src/libslic3r/Print.cpp
• All print/printer/material settings: src/libslic3r/PrintConfig.cpp
• GUI: src/slic3r/GUI/
• Core algorithms: src/libslic3r/ (GCode/, Fill/, Support/, Geometry/, Format/, Arachne/)
• Printer profiles: resources/profiles/[manufacturer].json

Critical Constraints

• Backward compatibility required for .3mf project files and printer profiles
• Cross-platform — all changes must work on Windows, macOS, and Linux
• Profile/format changes need version migration handling
• Dependencies built separately in deps/build/, then linked to main app

Code review focus areas

• Changes must not cause regressions in existing functionality, defaults, profiles, or project compatibility.
• Features gated by options must not affect existing behavior when those options are disabled.
• Changes should follow the existing code style and architecture. Architectural changes should be justified in code comments and the PR description.
• Add helper functions or utilities only when existing code cannot reasonably be reused. Avoid duplication.
• Keep code concise and clear. Manually simplify AI generated bloated codes before review.
• Include targeted tests or documented verification for behavior changes, especially in slicing logic, profiles, formats, and GUI defaults.
• For profile changes (resources/profiles/<Vendor>/**), check that version in the sibling resources/profiles/<Vendor>.json was bumped.
• For new or changed UI strings, check they follow Writing translatable strings in the source: no concatenated fragments, plural forms for counts, contexts for ambiguous words.
• For translation changes (localization/i18n/**/*.po), check that recurring terms match the Localization glossary for that language.

Localization & translations

Catalogs live in localization/i18n/<lang>/OrcaSlicer_<lang>.po; the template is OrcaSlicer.pot. See the Localization guide for the human-facing version of these principles.

Writing translatable strings in the source

Translators see one msgid at a time and cannot change the code around it, so each message must be complete in a single msgid. Use the wrapper that fits instead of assembling text from pieces:

• One msgid per sentence, with placeholders. Never build a message by concatenating translated fragments (_L("A") + name + _L(" is B")) or by splicing a translated word such as _L("left") into another sentence: the translator can't reorder or inflect the parts. Write format(_L("%1% is too close to others"), name).
• A count needs a plural form. Don't write file(s) or leave a verb unchanged after a number. Use _L_PLURAL("%1% object", "%1% objects", n). libslic3r has no plural lookup, so word the message so it doesn't depend on a count, or build it in the GUI.
• An ambiguous word needs a context. When a short string means different things in different places (verb or noun, a mode name, a CAD term), give each sense its own context with _L_CONTEXT/_u8L_CONTEXT/L_CONTEXT. Keep the most common sense without a context so its existing translations stay valid.
• Mark every user-visible string (_L/_u8L, or L where it is translated later) and list new source files in localization/i18n/list.txt: files that aren't listed are never extracted.
• Add a // TRN comment above a new string whose meaning or placeholders aren't obvious.
• Never choose behavior by comparing translated text; compare ids or flags.

See .claude/skills/orca-translations/references/source-audit.md for the full checklist.

Terminology

• Use the Localization glossary as the source of truth for recurring terms, so the same English term is always rendered the same way within a language, and terms that must stay in English (brand/product names, acronyms, materials, file formats, G-code tokens, macros/variables/identifiers) are not translated.
• If a term's established translation changes, update both the affected .po files and the glossary (localization_glossary.tsv, then regenerate) so they stay in sync.
• Translate the meaning, not the words. Check what the string actually controls before translating it — English reuses one word for different things. Flow ratio (multiplier), Flow Rate (throughput) and Flow Dynamics (pressure compensation) are three different terms; extruder may mean the toolhead, the feeder motor, or the nozzle depending on the string.
• Reuse one template per recurring message shape (Failed to connect to …, Are you sure you want to …?), even where the English wording varies.

Editing rules

• Only edit msgstr — never change msgid, and never "fix" wrong English in the translation alone. Report the source string instead.
• Preserve exactly: placeholders (%s, %d, %1%, %zu, %%), every \n (count and position, including leading/trailing), leading/trailing spaces, HTML tags, ℃, and the file's encoding and line endings.
• Never reorder positional arguments in a c-format string. If the msgid is %d then %s, that order must hold — swapping them breaks at runtime.
• msgctxt separates homonyms — always read it. Back/Camera View is the rear view of the 3D navigator, while Back/Navigation is the go-back button; Top exists in the Alignment, Layers and Camera View senses.
• When a string needs disambiguating, add context in the source (_L_CONTEXT/_u8L_CONTEXT), don't work around it in the translation.
• A literal % inside a string xgettext flagged possible-c-format will fail msgfmt. Fix it with a // xgettext:no-c-format, no-boost-format comment above the string in the source — do not mangle the translation or use %% in text that is never passed through printf.
• Plural entries: read nplurals from the catalog's Plural-Forms header (it is not always 2 — ja/ko/zh/th/vi use 1, ru/cs/pl/lt use 3, uk uses 4). Each form must be genuinely inflected for its quantity; repeating one sentence across all forms is a bug in Slavic/Baltic languages, though it is correct for Turkish and Hungarian.
• An entry whose msgstr equals its msgid is untranslated even though it is not empty; a plural entry with any empty form is likewise incomplete.
• Mark machine-produced translations with an # AI Translated translator comment. Don't add it to a human translation you didn't actually rewrite.
• When you can't be sure of a machine translation's meaning or UI wording, also add # Needs human review: <what to check>. Never use fuzzy for this — fuzzy entries are hidden from users.
• Don't reflow or re-wrap unrelated entries — keep the diff limited to the strings you changed.

Verifying

• scripts/run_gettext.bat --full (Windows) regenerates the template, merges every catalog and compiles the .mo files. It must exit 0.
• Or check a single catalog with msgfmt --check-format -o <out>.mo localization/i18n/<lang>/OrcaSlicer_<lang>.po.
• Fuzzy entries are not shown to users. If you correct one, clear its fuzzy flag, otherwise the fix never ships.