feat: Add support for style_id and get all style rules endpoint

Author: BriannaDelgado

DeepL/DeepLClient.cs

@@ -53,7 +53,7 @@ Task<WriteResult> RephraseTextAsync(
   ///   Client for the DeepL API. To use the DeepL API, initialize an instance of this class using your DeepL
   ///   Authentication Key. All functions are thread-safe, aside from <see cref="DeepLClient.Dispose" />.
   /// </summary>
-  public sealed class DeepLClient : Translator, IWriter, IGlossaryManager {
+  public sealed class DeepLClient : Translator, IWriter, IGlossaryManager, IStyleRuleManager {
     /// <summary>Initializes a new instance of the <see cref="AuthorizationException" /> class.</summary>
     /// <param name="message">The message that describes the error.</param>
     public DeepLClient(string authKey, DeepLClientOptions? options = null) : base(authKey, options) { }
@@ -104,6 +104,35 @@ public async Task<WriteResult[]> RephraseTextAsync(
       return rephrasedTexts.Improvements;
     }
 
+    /// <inheritdoc />
+    public async Task<StyleRuleInfo[]> GetAllStyleRulesAsync(
+          int? page = null,
+          int? pageSize = null,
+          bool? detailed = null,
+          CancellationToken cancellationToken = default) {
+      var queryParams = new List<(string Key, string Value)>();
+
+      if (page != null) {
+        queryParams.Add(("page", page.Value.ToString()));
+      }
+
+      if (pageSize != null) {
+        queryParams.Add(("page_size", pageSize.Value.ToString()));
+      }
+
+      if (detailed != null) {
+        queryParams.Add(("detailed", detailed.Value.ToString().ToLower()));
+      }
+
+      using var responseMessage = await _client
+            .ApiGetAsync("/v3/style_rules", cancellationToken, queryParams.ToArray()).ConfigureAwait(false);
+
+      await DeepLHttpClient.CheckStatusCodeAsync(responseMessage).ConfigureAwait(false);
+      var styleRuleList = await JsonUtils.DeserializeAsync<StyleRuleListResult>(responseMessage)
+            .ConfigureAwait(false);
+      return styleRuleList.StyleRules;
+    }
+
     /// <inheritdoc />
     public async Task<MultilingualGlossaryInfo> CreateMultilingualGlossaryAsync(
           string name,
@@ -694,5 +723,18 @@ private static (string Key, string Value)[] CreateLanguageQueryParams(
 
       return bodyParams;
     }
+
+    /// <summary>Class used for JSON-deserialization of style rule list results.</summary>
+    private readonly struct StyleRuleListResult {
+      /// <summary>Initializes a new instance of <see cref="StyleRuleListResult" />, used for JSON deserialization.</summary>
+      [JsonConstructor]
+      public StyleRuleListResult(StyleRuleInfo[] styleRules) {
+        StyleRules = styleRules;
+      }
+
+      /// <summary>Array of <see cref="StyleRuleInfo" /> objects holding style rule information.</summary>
+      [JsonPropertyName("style_rules")]
+      public StyleRuleInfo[] StyleRules { get; }
+    }
   }
 }

DeepL/IStyleRuleManager.cs

@@ -0,0 +1,28 @@
+// Copyright 2025 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+using System.Threading;
+using System.Threading.Tasks;
+using DeepL.Model;
+
+namespace DeepL {
+  public interface IStyleRuleManager {
+    /// <summary>Retrieves the list of all available style rules.</summary>
+    /// <param name="page">Optional page number for pagination, 0-indexed.</param>
+    /// <param name="pageSize">Optional number of items per page.</param>
+    /// <param name="detailed">
+    ///   Optional flag indicating whether to include detailed configuration rules in the configuredRules property.
+    /// </param>
+    /// <param name="cancellationToken">The cancellation token to cancel operation.</param>
+    /// <returns>Array of <see cref="StyleRuleInfo" /> objects representing the available style rules.</returns>
+    /// <exception cref="DeepLException">
+    ///   If any error occurs while communicating with the DeepL API, a
+    ///   <see cref="DeepLException" /> or a derived class will be thrown.
+    /// </exception>
+    Task<StyleRuleInfo[]> GetAllStyleRulesAsync(
+          int? page = null,
+          int? pageSize = null,
+          bool? detailed = null,
+          CancellationToken cancellationToken = default);
+  }
+}

DeepL/Model/StyleRuleInfo.cs

@@ -0,0 +1,141 @@
+// Copyright 2025 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace DeepL.Model {
+  /// <summary>Configuration rules for a style rule list.</summary>
+  public sealed class ConfiguredRules {
+    /// <summary>Initializes a new instance of <see cref="ConfiguredRules" />.</summary>
+    [JsonConstructor]
+    public ConfiguredRules(
+          Dictionary<string, string>? datesAndTimes,
+          Dictionary<string, string>? formatting,
+          Dictionary<string, string>? numbers,
+          Dictionary<string, string>? punctuation,
+          Dictionary<string, string>? spellingAndGrammar,
+          Dictionary<string, string>? styleAndTone,
+          Dictionary<string, string>? vocabulary) {
+      DatesAndTimes = datesAndTimes;
+      Formatting = formatting;
+      Numbers = numbers;
+      Punctuation = punctuation;
+      SpellingAndGrammar = spellingAndGrammar;
+      StyleAndTone = styleAndTone;
+      Vocabulary = vocabulary;
+    }
+
+    /// <summary>Date and time formatting rules.</summary>
+    [JsonPropertyName("dates_and_times")]
+    public Dictionary<string, string>? DatesAndTimes { get; }
+
+    /// <summary>Text formatting rules.</summary>
+    [JsonPropertyName("formatting")]
+    public Dictionary<string, string>? Formatting { get; }
+
+    /// <summary>Number formatting rules.</summary>
+    [JsonPropertyName("numbers")]
+    public Dictionary<string, string>? Numbers { get; }
+
+    /// <summary>Punctuation rules.</summary>
+    [JsonPropertyName("punctuation")]
+    public Dictionary<string, string>? Punctuation { get; }
+
+    /// <summary>Spelling and grammar rules.</summary>
+    [JsonPropertyName("spelling_and_grammar")]
+    public Dictionary<string, string>? SpellingAndGrammar { get; }
+
+    /// <summary>Style and tone rules.</summary>
+    [JsonPropertyName("style_and_tone")]
+    public Dictionary<string, string>? StyleAndTone { get; }
+
+    /// <summary>Vocabulary rules.</summary>
+    [JsonPropertyName("vocabulary")]
+    public Dictionary<string, string>? Vocabulary { get; }
+  }
+
+  /// <summary>Custom instruction for a style rule.</summary>
+  public sealed class CustomInstruction {
+    /// <summary>Initializes a new instance of <see cref="CustomInstruction" />.</summary>
+    [JsonConstructor]
+    public CustomInstruction(string label, string prompt, string? sourceLanguage) {
+      Label = label;
+      Prompt = prompt;
+      SourceLanguage = sourceLanguage;
+    }
+
+    /// <summary>Label for the custom instruction.</summary>
+    [JsonPropertyName("label")]
+    public string Label { get; }
+
+    /// <summary>Prompt text for the custom instruction.</summary>
+    [JsonPropertyName("prompt")]
+    public string Prompt { get; }
+
+    /// <summary>Optional source language code for the custom instruction.</summary>
+    [JsonPropertyName("source_language")]
+    public string? SourceLanguage { get; }
+  }
+
+  /// <summary>Information about a style rule list.</summary>
+  public sealed class StyleRuleInfo {
+    /// <summary>Initializes a new instance of <see cref="StyleRuleInfo" />.</summary>
+    [JsonConstructor]
+    public StyleRuleInfo(
+          string styleId,
+          string name,
+          DateTime creationTime,
+          DateTime updatedTime,
+          string language,
+          int version,
+          ConfiguredRules? configuredRules,
+          CustomInstruction[]? customInstructions) {
+      StyleId = styleId;
+      Name = name;
+      CreationTime = creationTime;
+      UpdatedTime = updatedTime;
+      Language = language;
+      Version = version;
+      ConfiguredRules = configuredRules;
+      CustomInstructions = customInstructions;
+    }
+
+    /// <summary>Unique ID assigned to the style rule list.</summary>
+    [JsonPropertyName("style_id")]
+    public string StyleId { get; }
+
+    /// <summary>User-defined name assigned to the style rule list.</summary>
+    [JsonPropertyName("name")]
+    public string Name { get; }
+
+    /// <summary>Time when the style rule list was created.</summary>
+    [JsonPropertyName("creation_time")]
+    public DateTime CreationTime { get; }
+
+    /// <summary>Time when the style rule list was last updated.</summary>
+    [JsonPropertyName("updated_time")]
+    public DateTime UpdatedTime { get; }
+
+    /// <summary>Language code for the style rule list.</summary>
+    [JsonPropertyName("language")]
+    public string Language { get; }
+
+    /// <summary>Version number of the style rule list.</summary>
+    [JsonPropertyName("version")]
+    public int Version { get; }
+
+    /// <summary>The predefined rules that have been enabled.</summary>
+    [JsonPropertyName("configured_rules")]
+    public ConfiguredRules? ConfiguredRules { get; }
+
+    /// <summary>Optional list of custom instructions.</summary>
+    [JsonPropertyName("custom_instructions")]
+    public CustomInstruction[]? CustomInstructions { get; }
+
+    /// <summary>Returns a string describing the style rule.</summary>
+    public override string ToString() => $"StyleRule \"{Name}\" ({StyleId})";
+  }
+}

DeepL/TextTranslateOptions.cs

@@ -26,6 +26,12 @@ public TextTranslateOptions(MultilingualGlossaryInfo glossary) : this() {
       GlossaryId = glossary.GlossaryId;
     }
 
+    /// <summary>Initializes a new <see cref="TextTranslateOptions" /> object including the given style rule.</summary>
+    /// <param name="styleRule">Style rule to use in translation.</param>
+    public TextTranslateOptions(StyleRuleInfo styleRule) : this() {
+      StyleId = styleRule.StyleId;
+    }
+
     /// <summary>
     ///   Specifies additional context to influence translations, that is not translated itself.
     ///   Characters in the `context` parameter are not counted toward billing.
@@ -41,6 +47,9 @@ public TextTranslateOptions(MultilingualGlossaryInfo glossary) : this() {
     /// <summary>Specifies the ID of a glossary to use with the translation.</summary>
     public string? GlossaryId { get; set; }
 
+    /// <summary>Specifies the ID of a style rule to use with the translation.</summary>
+    public string? StyleId { get; set; }
+
     /// <summary>Specifies a list of XML tags containing content that should not be translated.</summary>
     public List<string> IgnoreTags { get; } = new List<string>();
 

DeepL/Translator.cs

@@ -909,7 +909,8 @@ private String ConstructUserAgentString(bool sendPlatformInfo = true, AppInfo? a
             sourceLanguageCode,
             targetLanguageCode,
             options?.Formality,
-            options?.GlossaryId);
+            options?.GlossaryId,
+            options?.StyleId);
 
       // Always send show_billed_characters=1, remove when the API default is changed to true
       bodyParams.Add(("show_billed_characters", "1"));
@@ -971,13 +972,15 @@ private String ConstructUserAgentString(bool sendPlatformInfo = true, AppInfo? a
     /// <param name="targetLanguageCode">Language code of translation target language.</param>
     /// <param name="formality">Formality option for translation.</param>
     /// <param name="glossaryId">Optional ID of glossary to use for translation.</param>
+    /// <param name="styleId">Optional ID of style rule to use for translation.</param>
     /// <returns>List of tuples containing the parameters to include in HTTP request.</returns>
     /// <exception cref="ArgumentException">If the specified languages or options are invalid.</exception>
     private static List<(string Key, string Value)> CreateCommonHttpParams(
           string? sourceLanguageCode,
           string targetLanguageCode,
           Formality? formality,
-          string? glossaryId) {
+          string? glossaryId,
+          string? styleId = null) {
       targetLanguageCode = LanguageCode.Standardize(targetLanguageCode);
       sourceLanguageCode = sourceLanguageCode == null ? null : LanguageCode.Standardize(sourceLanguageCode);
 
@@ -996,6 +999,10 @@ private String ConstructUserAgentString(bool sendPlatformInfo = true, AppInfo? a
         bodyParams.Add(("glossary_id", glossaryId));
       }
 
+      if (styleId != null) {
+        bodyParams.Add(("style_id", styleId));
+      }
+
       switch (formality) {
         case null:
         case Formality.Default:

DeepLTests/StyleRuleTest.cs

@@ -0,0 +1,71 @@
+// Copyright 2025 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+using System.Threading.Tasks;
+using DeepL;
+using Xunit;
+
+namespace DeepLTests {
+  public sealed class StyleRuleTest : BaseDeepLTest {
+    private const string DefaultStyleId = "dca2e053-8ae5-45e6-a0d2-881156e7f4e4";
+
+    [MockServerOnlyFact]
+    public async Task TestGetAllStyleRules() {
+      var client = CreateTestClient();
+      var styleRules = await client.GetAllStyleRulesAsync(0, 10, true);
+      Assert.NotNull(styleRules);
+      Assert.True(styleRules.Length > 0);
+      Assert.Equal(DefaultStyleId, styleRules[0].StyleId);
+      Assert.Equal("Default Style Rule", styleRules[0].Name);
+      Assert.Equal("en", styleRules[0].Language);
+      Assert.Equal(1, styleRules[0].Version);
+      Assert.NotNull(styleRules[0].ConfiguredRules);
+      Assert.NotNull(styleRules[0].CustomInstructions);
+    }
+
+    [MockServerOnlyFact]
+    public async Task TestGetAllStyleRulesWithoutDetailed() {
+      var client = CreateTestClient();
+      var styleRules = await client.GetAllStyleRulesAsync();
+
+      Assert.NotNull(styleRules);
+      Assert.True(styleRules.Length > 0);
+      Assert.Equal(DefaultStyleId, styleRules[0].StyleId);
+      Assert.Null(styleRules[0].ConfiguredRules);
+      Assert.Null(styleRules[0].CustomInstructions);
+    }
+
+    [MockServerOnlyFact]
+    public async Task TestTranslateTextWithStyleId() {
+      // Note: this test may use the mock server that will not translate the text,
+      // therefore we do not check the translated result.
+      var client = CreateTestClient();
+      const string exampleText = "Hallo, Welt!";
+
+      var result = await client.TranslateTextAsync(
+            exampleText,
+            "de",
+            "en-US",
+            new TextTranslateOptions { StyleId = DefaultStyleId });
+
+      Assert.NotNull(result);
+    }
+
+    [MockServerOnlyFact]
+    public async Task TestTranslateTextWithStyleRuleInfo() {
+      var client = CreateTestClient();
+      var styleRules = await client.GetAllStyleRulesAsync();
+      var styleRule = styleRules[0];
+      const string exampleText = "Hallo, Welt!";
+
+      var result = await client.TranslateTextAsync(
+            exampleText,
+            "de",
+            "en-US",
+            new TextTranslateOptions(styleRule));
+
+      Assert.NotNull(result);
+    }
+  }
+}