(GH-538) Add schema_i18n! helper macro

[michaeltlombardi]

PR Summary

This change:

1. Adds the new schema_i18n() helper method to the DscRepoSchema trait, which concatenates the input value to the root key defined in the new SCHEMA_I18N_ROOT_KEY associated constant.

   This method retrieves the translation and returns an error if the translation isn't defined. This is different from the behavior for calling t!() directly, which emits the lookup key as the output string when that key isn't defined.

   Returning an error allows us to call unwrap() on the lookup, raising a panic on missing values and stopping the tests.

2. Defines the schema_i18n!() macro, which simplifies invoking the new method for more readable type and schema definitions.

3. Updates the derive macro for DscRepoSchema to automatically define the value of SCHEMA_I18N_ROOT_KEY as the joining of the SCHEMA_FOLDER_PATH and SCHEMA_FILE_BASE_NAME associated constants. The path separators are replaced with periods (.) and the two values are joined with a period.

4. Updates the type definitions in dsc-lib::types to use the new macro.

5. Updates the dsc_i18n test suite to ignore YAML files, which should exclusively be used for schema documentation keywords. This shifts the testing logic for schemas to ensuring they don't panic during generation, as with the schema_for!() macro.

PR Context

Prior to this change, defining the documentation keywords for schemas in dsc-lib and other crates required passing long lookup keys for i18n, like:

t!("schemas.definitions.resourceVersionReq.semanticVariant.description")

These long lines require a lot of repetition and make the code more difficult to read and maintain. We rely on the pester tests in dsc/tests/dsc_i18n.tests.ps1 to verify i18n.

Currently, we define all program-specific translation strings in <language>.toml files for every crate. We define schema-specific translations in YAML files. We previously updated the i18n tests to account for this and check that every defined translation is used and that every used translation is defined.

With a new helper macro for looking up schema documentation, we can instead panic when a schema documentation translation entry isn't defined, which is caught by the rust testing for schemas (a missing translation triggers a panic on schema_for!()). In the future, we may be able to drive improved static analysis and testing for type definitions to ensure they are fully documented and that all defined translations are being used.

For now, we can improve the maintainability and readability of our type definitions while ensuring that we raise a panic when an expected documentation keyword isn't defined.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a schema-specific i18n helper (schema_i18n() + schema_i18n!()) to make JSON Schema documentation keyword lookups shorter and fail-fast, then migrates schema/type definitions and tests to rely on it.

Changes:

• Introduces SCHEMA_I18N_ROOT_KEY + schema_i18n() on DscRepoSchema, plus the schema_i18n!() macro.
• Updates dsc-lib type schemas to use schema_i18n!() instead of long t!(...) keys.
• Updates jsonschema integration tests/locales and refactors VS Code keyword locale keys (YAML → TOML, camelCase → snake_case).

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
lib/dsc-lib/src/types/tag_list.rs	Switches schema docs to schema_i18n!() and updates schema metadata attributes.
lib/dsc-lib/src/types/tag.rs	Uses schema_i18n!() for schema docs and derives DscRepoSchema.
lib/dsc-lib/src/types/semantic_version_req.rs	Uses schema_i18n!() and changes schema base name for SemanticVersionReq.
lib/dsc-lib/src/types/semantic_version.rs	Uses schema_i18n!() for schema docs.
lib/dsc-lib/src/types/resource_version_req.rs	Uses schema_i18n!() for schema docs for enum + variants.
lib/dsc-lib/src/types/resource_version.rs	Uses schema_i18n!() for schema docs for enum + variants.
lib/dsc-lib/src/types/fully_qualified_type_name.rs	Uses schema_i18n!() for schema docs.
lib/dsc-lib/src/types/exit_codes_map.rs	Uses schema_i18n!() for schema docs in JsonSchema impl.
lib/dsc-lib/src/types/date_version.rs	Uses schema_i18n!() for schema docs in JsonSchema impl.
lib/dsc-lib-jsonschema/tests/integration_locales/schemas.yaml	Adds YAML test locales for schema doc keyword integration tests.
lib/dsc-lib-jsonschema/tests/integration/main.rs	Enables rust_i18n for integration tests.
lib/dsc-lib-jsonschema/tests/integration/dsc_repo/derive_dsc_repo_schema.rs	Adds integration assertions validating translated schema doc keywords.
lib/dsc-lib-jsonschema/src/vscode/keywords/suggest_sort_text.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/pattern_error_message.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/markdown_enum_descriptions.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/markdown_description.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/error_message.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/enum_sort_texts.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/enum_details.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/enum_descriptions.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/do_not_suggest.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/deprecation_message.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/default_snippets.rs	Renames i18n lookup keys to snake_case (nested keys).
lib/dsc-lib-jsonschema/src/vscode/keywords/completion_detail.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/allow_trailing_commas.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/vscode/keywords/allow_comments.rs	Renames i18n lookup keys to snake_case.
lib/dsc-lib-jsonschema/src/tests/dsc_repo.rs	Updates test trait impls for new SCHEMA_I18N_ROOT_KEY + schema_i18n().
lib/dsc-lib-jsonschema/src/dsc_repo/mod.rs	Re-exports missing translation error + macro wiring.
lib/dsc-lib-jsonschema/src/dsc_repo/macros.rs	Adds schema_i18n!() helper macro.
lib/dsc-lib-jsonschema/src/dsc_repo/dsc_repo_schema.rs	Extends DscRepoSchema with i18n const + lookup fn and adds missing-translation error type.
lib/dsc-lib-jsonschema/locales/vscode.yaml	Removes VS Code locales from YAML.
lib/dsc-lib-jsonschema/locales/en-us.toml	Adds VS Code locales and new missing-translation error message.
lib/dsc-lib-jsonschema-macros/src/derive/dsc_repo_schema.rs	Derive macro now generates SCHEMA_I18N_ROOT_KEY and schema_i18n() implementation.
dsc/tests/dsc_i18n.tests.ps1	Stops loading YAML locale files for i18n usage/definition checks.

Comments suppressed due to low confidence (1)

lib/dsc-lib/src/types/semantic_version_req.rs:1

• Changing base_name changes the generated schema $id/URI and likely the emitted schema filename/path, which can be a breaking change for external consumers. If the goal is only to align i18n lookup roots, consider keeping the existing base_name and overriding i18n_root_key via #[dsc_repo_schema(i18n_root_key = \"...\")] instead; otherwise, document this as an intentional schema ID change (and align any published schema references/versioning accordingly).

[SteveL-MSFT]

Does this increase the binary size in any impactful way? If so, perhaps we can do the check only on debug builds?

[michaeltlombardi]

I don't think so:

1. The size of the implementation for this is very small - the method itself is very small and is primarily calling existing code.
2. The implementation here mirrors the expansion of the t!() macro except that we error on a missing translation string instead of emitting the failed lookup as the translation string, e.g t!("unedefined.translation") would emit "undefined.translation".
3. The majority of the size comes from the existing i18n macros, particularly the translation lookup map tat it generates.
4. I'm not sure how we can effectively gate this on build configuration without either starting the work to separate the dsc schema command into its own crate or stripping the schema documentation keywords. We could possibly use cfg_attr but that will get very messy very quickly for annotating structs.