i18n support

[hesch]

User story

As a user of Spring REST Docs, I want to be able to generate documentation in multiple languages.

Goals

1. Generate each snippet multiple times for each locale
2. Put them into locale specific subdirectories
   a. /build/generated-snippets/en-US/{request-name}/request-parameters.adoc
   b. /build/generated-snippets/de-DE/{request-name}/request-parameters.adoc
3. Then the user can mirror the same structure in their documentation and import from the language specific subdirs

Design

Currently there are filters provided for the request library that holds a list of Snippets, each with a list of Descriptors. For i18n support the library could just generate Snippets for each locale and set a locale attribute for them. Then each Descriptor would change their description based on the locale.

Let's break this down into steps:

1. Implement a way for descriptors to access Snippet attributes
2. Implement a new LocaleAwareDescriptor that could either take something like a Map<Locale, String> or a ResourceBundle
3. Add a new WriterResolver that changes the output path based on locale
4. Add helper methods e.g. documentTranslated(Snippets... snippets) that will handle duplicating Snippets for each locale
5. Add configuration specifying which locales should be generated

Constraint handling

1. Refactor Constraints to also be Descriptors
2. Use the locale from its template to load the correct ResourceBundle

Considerations

1 and 3 from the design above can be implemented in the core lib as a non breaking changes first. Then 2,4 and 5 can be implemented in a separate lib adding i18n capabilities.

Unfortunately the proposed changes in constraint handling are breaking changes.

[wilkinsona]

Thanks for the suggestions.

Implement a way for descriptors to access Snippet attributes

Conceptually, this relationship feels like it's the wrong way around to me.

My first impression is that it would be better for the localization to be done in the test code. For example, building on JUnit's @TestTemplate and/or @ParameterizedTest, it would be possible for the same test to be invoked multiple times with different locales, ResourceBundles and so on. Rather than hardcoding the descriptions, the tests can then vary the descriptions based on the locale or resource bundle that's passed into the test method.

Constraint descriptions can already be provided using a resource bundle. Rather than using the default constructor of ResourceBundleConstraintDescriptionResolver, the overloaded ResourceBundleConstraintDescriptionResolver(ResourceBundle) constructor could be used instead, passing in a ResourceBundle that appropriate for the locale that's currently being tested.

Perhaps you've already explored this direction and it didn't work out? If so, it would be useful to hear why. If not, does it sound like it would meet your needs?

[spring-projects-issues]

If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.

[spring-projects-issues]

Closing due to lack of requested feedback. If you would like us to look at this issue, please provide the requested information and we will re-open the issue.