haveapi 0.32.1 → 0.32.2

data/lib/haveapi/client_examples/dynamic_helpers.rb

@@ -47,9 +47,9 @@ module HaveAPI::ClientExamples
         result = {}
         value.each do |key, entry|
           unless key.is_a?(String) || key.is_a?(Symbol)
-            raise Unsupported, 'This sample has a non-string object key.'
+            raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.object_key')
           end
-          raise Unsupported, 'This sample has duplicate serialized object keys.' if result.has_key?(key.to_s)
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.duplicate_object_keys') if result.has_key?(key.to_s)
 
           result[key.to_s] = json_data(entry)
         end
@@ -59,17 +59,17 @@ module HaveAPI::ClientExamples
       when String, Integer, TrueClass, FalseClass, NilClass
         value
       when Float
-        raise Unsupported, 'This sample has a non-finite number.' unless value.finite?
+        raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.non_finite_number') unless value.finite?
 
         value
       else
-        raise Unsupported, 'This sample contains a value without a supported literal representation.'
+        raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.literal')
       end
     end
 
     def structured_sample(sample)
       unless sample.is_a?(Hash) && (!field(sample, :request).nil? || !field(sample, :response).nil?)
-        raise Unsupported, 'This example contains prose only; no executable request is supplied.'
+        raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.prose_only')
       end
 
       %i[global object].each do |scope|
@@ -77,29 +77,29 @@ module HaveAPI::ClientExamples
 
         input = field(field(field(current_action, :meta), scope), :input)
         if field(input, :parameters, {}).values.any? { |parameter| field(parameter, :required) }
-          raise Unsupported, 'This action requires input metadata that the sample format cannot supply.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.input_metadata')
         end
       end
 
       placeholders = field(current_action, :path, '').scan(/\{([a-zA-Z0-9_-]+)\}/).flatten
       values = field(sample, :path_params, []) || []
       unless values.is_a?(Array) && values.length == placeholders.length
-        raise Unsupported, 'The sample does not supply every action path argument.'
+        raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.path_arguments_missing')
       end
       unless values.all? { |value| value.is_a?(String) || value.is_a?(Integer) }
-        raise Unsupported, 'Action path arguments must be strings or integers.'
+        raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.path_argument_type')
       end
 
       request = field(sample, :request)
       input = field(current_action, :input)
       if !request.nil? && input.nil? && request != {}
-        raise Unsupported, 'The sample supplies input for an action without an input description.'
+        raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.input_description_missing')
       end
 
       if request.is_a?(Hash) && input
         known = field(input, :parameters, {}).keys.map(&:to_s)
         unless (request.keys.map(&:to_s) - known).empty?
-          raise Unsupported, 'The sample contains input parameters absent from the visible description.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.input_hidden')
         end
       end
       [placeholders.zip(values).to_h, json_data(request)]

data/lib/haveapi/client_examples/go_client.rb

@@ -34,7 +34,7 @@ module HaveAPI::ClientExamples
 
     def render_documentation(kind, sample: nil, **)
       unless context && self.class.available?(context)
-        return { status: :limitation, reason: 'A Go API client profile is required.' }.freeze
+        return { status: :limitation, reason: HaveAPI.t('haveapi.documentation.limitations.go_profile') }.freeze
       end
 
       selected = kind == :example ? context.with(sample:) : context

data/lib/haveapi/client_examples/http.rb

@@ -42,17 +42,17 @@ module HaveAPI::ClientExamples
 
       when :oauth2
         <<~END
-          # 1) Request authorization code
+          #{comment_lines(example_comment('http_oauth_code', default: '1) Request authorization code'), '# ')}
           GET #{desc[:authorize_path]}?response_type=code&client_id=example-client&state=example-state&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback HTTP/1.1
           Host: #{host}
 
-          # 2) The user logs in using this API
+          #{comment_lines(example_comment('http_oauth_login', default: '2) The user logs in using this API'), '# ')}
 
-          # 3) The API then redirects the user back to the client application
+          #{comment_lines(example_comment('http_oauth_redirect', default: '3) The API then redirects the user back to the client application'), '# ')}
           GET /callback?code=example-code&state=example-state
           Host: client-application
 
-          # 4) The client application requests access token
+          #{comment_lines(example_comment('http_oauth_token', default: '4) The client application requests access token'), '# ')}
           POST #{desc[:token_path]}
           Content-Type: application/x-www-form-urlencoded
 

data/lib/haveapi/client_examples/js_client.rb

@@ -32,7 +32,7 @@ module HaveAPI::ClientExamples
       when Array
         "[#{value.map { |entry| js_literal(entry) }.join(', ')}]"
       when Integer
-        raise Unsupported, 'This sample contains an integer outside JavaScript exact precision.' if value.abs > 9_007_199_254_740_991
+        raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.javascript_integer') if value.abs > 9_007_199_254_740_991
 
         value.to_s
       else
@@ -103,7 +103,7 @@ module HaveAPI::ClientExamples
       return nil unless field(current_action, :auth)
 
       method = %i[token basic oauth2].find { |name| supported_auth?(name) }
-      raise Unsupported, 'This action requires an authentication provider unsupported by this client.' unless method
+      raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.action_authentication') unless method
 
       options = {
         token: '{token: "example-token"}',
@@ -118,7 +118,7 @@ module HaveAPI::ClientExamples
     end
 
     def auth(method, description)
-      return limitation('This authentication provider is not advertised or supported by this client.') unless supported_auth?(method)
+      return limitation(HaveAPI.t('haveapi.documentation.limitations.authentication_provider')) unless supported_auth?(method)
 
       code_result do
         options = case method.to_sym
@@ -140,7 +140,7 @@ module HaveAPI::ClientExamples
                          end
         source = program(thorough? ? "console.log(\"Authenticated\");\n" : '', authentication:)
         if method.to_sym == :oauth2
-          source = "// Use an existing access token; this client does not run an OAuth authorization flow.\n#{source}"
+          source = "#{comment_lines(example_comment('js_existing_oauth', default: 'Use an existing access token; this client does not run an OAuth authorization flow.'), '// ')}\n#{source}"
         end
         source
       end
@@ -169,16 +169,16 @@ module HaveAPI::ClientExamples
       code_result do
         path, request = structured_sample(sample)
         if request.is_a?(Array)
-          raise Unsupported, 'This JavaScript client accepts object input only; list input cannot be represented without dropping values.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.javascript_list_input')
         end
         if !request.nil? && !request.is_a?(Hash)
-          raise Unsupported, 'This JavaScript client requires object input.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.javascript_object_input')
         end
         if !asynchronous? && field(field(current_action, :input), :parameters, {}).keys.any? { |name| %w[hasOwnProperty __proto__].include?(name.to_s) }
-          raise Unsupported, 'This callback client cannot safely represent this input parameter name.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.callback_parameter_name')
         end
         if request && %w[GET OPTIONS].include?(field(current_action, :method).to_s.upcase) && request.values.any? { |value| value.is_a?(Hash) || value.is_a?(Array) }
-          raise Unsupported, 'This JavaScript client cannot preserve nested values in query input.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.javascript_nested_query')
         end
 
         args = path.values.map { |value| js_literal(value) }
@@ -191,7 +191,7 @@ module HaveAPI::ClientExamples
           body << "console.log(result.value);\n"
           body << "console.log(result.response.meta);\n" if thorough?
           if field(current_action, :blocking)
-            body << "// Request success alone does not establish operation completion.\n"
+            body << "#{comment_lines(example_comment('js_request_completion', default: 'Request success alone does not establish operation completion.'), '// ')}\n"
             body << "const completed = await api.waitForCompletion(result, {timeoutMs: 300000});\nconsole.log(completed.state);\n"
           end
         else
@@ -209,7 +209,7 @@ module HaveAPI::ClientExamples
           options << "  console.log(reply.meta());\n" if thorough?
           options << "}\n"
           body << "action.directInvoke(#{(args + ["{\n#{indent(options)}}"]).join(', ')});\n"
-          body << "// This prints the initial response; use its action-state metadata to monitor completion.\n" if field(current_action, :blocking)
+          body << "#{comment_lines(example_comment('js_initial_response', default: 'This prints the initial response; use its action-state metadata to monitor completion.'), '// ')}\n" if field(current_action, :blocking)
         end
         authentication = action_authentication
         thorough? ? program(body, authentication:) : body

data/lib/haveapi/client_examples/php_client.rb

@@ -29,7 +29,7 @@ module HaveAPI::ClientExamples
         } catch (\\HaveAPI\\Client\\Exception\\Base $error) {
             echo $error->getMessage() . "\\n";
         } catch (\\Exception $error) {
-            // Dependency failures still propagate to the application.
+        #{comment_lines(example_comment('dependency_failures', default: 'Dependency failures still propagate to the application.'), '    // ')}
             echo $error->getMessage() . "\\n";
             throw $error;
         }
@@ -60,51 +60,50 @@ module HaveAPI::ClientExamples
                  <<~END
                    #{initialization.chomp}
 
-                   // Get token using username and password
+                   #{comment_lines(example_comment('token_credentials', default: 'Get token using username and password'), '// ')}
                    $api->authenticate('token', #{token_options(desc)});
 
-                   // Next time, the client can authenticate using the token directly
+                   #{comment_lines(example_comment('token_reuse_next', default: 'Next time, the client can authenticate using the token directly'), '// ')}
                    $api->authenticate('token', ['token' => 'example-token']);
                  END
 
                when :oauth2
                  <<~END
-                   // OAuth2 requires session
+                   #{comment_lines(example_comment('oauth_session', default: 'OAuth2 requires session'), '// ')}
                    session_start();
 
-                   // Client instance
+                   #{comment_lines(example_comment('client_instance', default: 'Client instance'), '// ')}
                    #{initialization}
-                   // Check if we already have an access token
+                   #{comment_lines(example_comment('oauth_check_token', default: 'Check if we already have an access token'), '// ')}
                    if (isset($_SESSION['access_token'])) {
-                       // We're already authenticated, reuse the existing access token
+                   #{comment_lines(example_comment('oauth_reuse_token', default: 'We\'re already authenticated, reuse the existing access token'), '    // ')}
                        $api->authenticate('oauth2', ['access_token' => $_SESSION['access_token']]);
                    } else {
-                       // Follow the OAuth2 authorization process to get an access token using
-                       // authorization code
+                   #{comment_lines(example_comment('oauth_code_flow', default: "Follow the OAuth2 authorization process to get an access token using\nauthorization code"), '    // ')}
                        $api->authenticate('oauth2', [
-                           // Client id and secret are given by the API server
+                   #{comment_lines(example_comment('oauth_client_credentials', default: 'Client id and secret are given by the API server'), '        // ')}
                            'client_id' => 'example-client',
                            'client_secret' => 'example-client-secret',
 
-                           // This example code should run on the URL below
+                   #{comment_lines(example_comment('oauth_callback_url', default: 'This example code should run on the URL below'), '        // ')}
                            'redirect_uri' => 'https://your-client.tld/oauth2-callback',
 
-                           // Scopes are specific to the API implementation
+                   #{comment_lines(example_comment('oauth_scopes', default: 'Scopes are specific to the API implementation'), '        // ')}
                            'scope' => 'all',
                        ]);
 
                        $provider = $api->getAuthenticationProvider();
 
-                       // We don't have authorization code yet, request one
+                   #{comment_lines(example_comment('oauth_need_code', default: 'We don\'t have authorization code yet, request one'), '    // ')}
                        if (!isset($_GET['code'])) {
-                           // Redirect the user to the authorization endpoint
+                   #{comment_lines(example_comment('oauth_redirect', default: 'Redirect the user to the authorization endpoint'), '        // ')}
                            $provider->requestAuthorizationCode();
                            exit;
                        } else {
-                           // Request access token using the token endpoint
+                   #{comment_lines(example_comment('oauth_request_token', default: 'Request access token using the token endpoint'), '        // ')}
                            $provider->requestAccessToken();
 
-                           // Store the access token in the session
+                   #{comment_lines(example_comment('oauth_store_token', default: 'Store the access token in the session'), '        // ')}
                            $_SESSION['access_token'] = $provider->jsonSerialize();
                        }
                    }
@@ -151,7 +150,7 @@ module HaveAPI::ClientExamples
       return "$api->authenticate('basic', ['user' => 'user', 'password' => 'secret']);" if providers.include?('basic')
       return "$api->authenticate('oauth2', ['access_token' => ['access_token' => 'example-access-token']]);" if providers.include?('oauth2')
 
-      raise HaveAPI::ClientExample::UnsupportedAuthentication, 'This action requires authentication unsupported by this client.'
+      raise HaveAPI::ClientExample::UnsupportedAuthentication, HaveAPI.t('haveapi.documentation.limitations.action_authentication')
     end
 
     def example(sample)
@@ -171,7 +170,7 @@ module HaveAPI::ClientExamples
       out << if sample[:status]
                response(sample)
              else
-               '// Throws exception \\HaveAPI\\Client\\Exception\\ActionFailed'
+               comment_lines(example_comment('throws_exception', default: 'Throws exception %{exception}', exception: '\\HaveAPI\\Client\\Exception\\ActionFailed'), '// ')
              end
       thorough? ? with_error_handling(["#{initialization}$api->setup();", credentials, out.chomp].reject(&:empty?).join("\n\n")) : out
     rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
@@ -183,16 +182,16 @@ module HaveAPI::ClientExamples
 
       case action[:output][:layout]
       when :hash
-        out << "// $reply is an instance of \\HaveAPI\\Client\\Response\n"
-        out << "// $reply->getResponse() returns an associative array of output parameters:\n"
+        out << "#{comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: '$reply', type: '\\HaveAPI\\Client\\Response'), '// ')}\n"
+        out << "#{comment_lines(example_comment('response_associative', default: '%{call} returns an associative array of output parameters:', call: '$reply->getResponse()'), '// ')}\n"
         out << format_parameters(:output, sample[:response] || {}, '// ')
 
       when :hash_list
-        out << "// $reply is an instance of \\HaveAPI\\Client\\Response\n"
-        out << "// $reply->getResponse() returns an array of associative arrays:\n"
+        out << "#{comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: '$reply', type: '\\HaveAPI\\Client\\Response'), '// ')}\n"
+        out << "#{comment_lines(example_comment('response_associative_arrays', default: '%{call} returns an array of associative arrays:', call: '$reply->getResponse()'), '// ')}\n"
 
       when :object
-        out << "// $reply is an instance of \\HaveAPI\\Client\\ResourceInstance\n"
+        out << "#{comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: '$reply', type: '\\HaveAPI\\Client\\ResourceInstance'), '// ')}\n"
 
         (sample[:response] || {}).each do |pn, pv|
           param = action[:output][:parameters][pn]
@@ -210,7 +209,7 @@ module HaveAPI::ClientExamples
             out << ")\n"
 
           elsif param[:type] == 'Custom'
-            out << "// $reply->#{pn} is a custom type"
+            out << comment_lines(example_comment('custom_type', default: '%{variable} is a custom type', variable: "$reply->#{pn}"), '// ')
 
           else
             out << "// $reply->#{pn} = #{PP.pp(pv, '')}"
@@ -218,7 +217,7 @@ module HaveAPI::ClientExamples
         end
 
       when :object_list
-        out << '// $reply is an instance of \\HaveAPI\\Client\\ResourceInstanceList'
+        out << comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: '$reply', type: '\\HaveAPI\\Client\\ResourceInstanceList'), '// ')
       end
 
       out

data/lib/haveapi/client_examples/python_client.rb

@@ -70,20 +70,20 @@ module HaveAPI::ClientExamples
     end
 
     def init
-      code_result { program(thorough? ? "print(\"Discovery complete\")\n" : "# Call API actions inside this block.\npass\n") }
+      code_result { program(thorough? ? "print(\"Discovery complete\")\n" : "#{comment_lines(example_comment('python_actions', default: 'Call API actions inside this block.'), '# ')}\npass\n") }
     end
 
     def auth(method, description)
-      return limitation('This authentication provider is not advertised or supported by this client.') unless supported_auth?(method)
+      return limitation(HaveAPI.t('haveapi.documentation.limitations.authentication_provider')) unless supported_auth?(method)
 
       code_result do
-        body = thorough? ? "print(\"Authenticated\")\n" : "# Call API actions inside this block.\npass\n"
+        body = thorough? ? "print(\"Authenticated\")\n" : "#{comment_lines(example_comment('python_actions', default: 'Call API actions inside this block.'), '# ')}\npass\n"
         case method.to_sym
         when :basic
           program(body, imports: ['BasicAuth'], auth: 'BasicAuth("user", "secret")')
         when :oauth2
           source = program(body, imports: ['OAuth2Auth'], auth: 'OAuth2Auth("example-access-token")')
-          "# Use an existing access token; OAuth acquisition and refresh are outside this client.\n#{source}"
+          "#{comment_lines(example_comment('python_existing_oauth', default: 'Use an existing access token; OAuth acquisition and refresh are outside this client.'), '# ')}\n#{source}"
         when :token
           if token_login_fields(description).empty?
             program(body, imports: ['TokenAuth'], auth: 'TokenAuth("example-token")')
@@ -112,13 +112,13 @@ module HaveAPI::ClientExamples
         path, request = structured_sample(sample)
         method = field(current_action, :method).to_s.upcase
         unless %w[GET POST PUT DELETE].include?(method)
-          raise Unsupported, 'This Python client supports GET, POST, PUT and DELETE actions only.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.python_method')
         end
         unless request.nil? || request.is_a?(Hash) || request.is_a?(Array)
-          raise Unsupported, 'This Python client requires object or list input.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.python_input')
         end
         if request.is_a?(Array) && field(field(current_action, :input), :namespace).to_s.empty?
-          raise Unsupported, 'This Python client requires a namespace for list input.'
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.python_list_namespace')
         end
 
         check_get_sample(request) if method == 'GET'
@@ -134,7 +134,7 @@ module HaveAPI::ClientExamples
         body << "print(response.meta)\n" if thorough?
         if field(current_action, :blocking)
           body << <<~PY
-            # A request timeout does not cancel a server operation.
+            #{comment_lines(example_comment('timeout_no_cancel', default: 'A request timeout does not cancel a server operation.'), '# ')}
             if response.operation is not None:
                 completed = #{await_prefix}response.operation.wait(timeout=300, interval=1)
                 print(completed)
@@ -142,7 +142,7 @@ module HaveAPI::ClientExamples
         end
         if field(current_action, :auth)
           method = %i[token basic oauth2].find { |name| supported_auth?(name) }
-          raise Unsupported, 'This action requires an authentication provider unsupported by this client.' unless method
+          raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.action_authentication') unless method
 
           provider, auth = {
             token: ['TokenAuth', 'TokenAuth("example-token")'],
@@ -161,7 +161,7 @@ module HaveAPI::ClientExamples
     end
 
     def action_fragment(body)
-      asynchronous? ? "# Run inside an async function after initializing api.\n#{body}" : body
+      asynchronous? ? "#{comment_lines(example_comment('python_async_context', default: 'Run inside an async function after initializing api.'), '# ')}\n#{body}" : body
     end
 
     def check_get_sample(request)
@@ -180,7 +180,7 @@ module HaveAPI::ClientExamples
       end)
       return if safe_namespace && safe_request
 
-      raise Unsupported, 'Python GET examples support flat scalar input with bracket-free names; Custom values must be strings or nullable nulls.'
+      raise Unsupported, HaveAPI.t('haveapi.documentation.limitations.python_get_input')
     end
   end
 end

data/lib/haveapi/client_examples/ruby_cli.rb

@@ -23,30 +23,27 @@ module HaveAPI::ClientExamples
       case method
       when :basic
         <<~END
-          # Provide credentials on command line
+          #{comment_lines(example_comment('cli_credentials', default: 'Provide credentials on command line'), '# ')}
           #{init} --auth basic --user user --password secret
 
-          # If username or password isn't provided, the user is asked on stdin
+          #{comment_lines(example_comment('cli_ask_stdin', default: 'If username or password isn\'t provided, the user is asked on stdin'), '# ')}
           #{init} --auth basic --user user
           # Password: secret
         END
 
       when :token
         <<~END
-          # Get token using username and password and save it to disk
-          # Note that the client always has to call some action. APIs should provide
-          # an action to get information about the current user, so that's what we're
-          # calling now.
+          #{comment_lines(example_comment('cli_save_token', default: 'Get token using username and password and save it to disk'), '# ')}
+          #{comment_lines(example_comment('cli_action_required', default: "Note that the client always has to call some action. APIs should provide\nan action to get information about the current user, so that's what we're\ncalling now."), '# ')}
           #{init} --auth token #{auth_token_credentials(desc, password: false).map { |k, v| "#{Shellwords.escape("--#{k}")} #{Shellwords.escape(v.to_s)}" }.join(' ')} --save user current
           # Password: secret
 
-          # Now the token is read from disk and the user does not have to provide username
-          # nor password and be authenticated
+          #{comment_lines(example_comment('cli_read_token', default: "Now the token is read from disk and the user does not have to provide username\nnor password and be authenticated"), '# ')}
           #{init} user current
         END
 
       when :oauth2
-        '# OAuth2 is not supported by HaveAPI Ruby CLI.'
+        comment_lines(example_comment('cli_oauth_unsupported', default: 'OAuth2 is not supported by HaveAPI Ruby CLI.'), '# ')
       end
     rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
       { status: :limitation, reason: e.message }.freeze

data/lib/haveapi/client_examples/ruby_client.rb

@@ -14,11 +14,19 @@ module HaveAPI::ClientExamples
     end
 
     def initialization
-      "require 'haveapi/client'\n\napi = HaveAPI::Client.new(#{base_url.dump}, version: #{version.to_s.dump})\n"
+      "#{client_library}#{client_initialization}"
+    end
+
+    def client_library
+      "require 'haveapi/client'\n\n"
+    end
+
+    def client_initialization
+      "api = HaveAPI::Client.new(#{base_url.dump}, version: #{version.to_s.dump})\n"
     end
 
     def with_error_handling(body)
-      <<~RUBY
+      client_library + <<~RUBY
         begin
         #{body.lines.map { |line| line == "\n" ? line : "  #{line}" }.join.chomp}
         rescue HaveAPI::Client::ValidationError => error
@@ -35,7 +43,7 @@ module HaveAPI::ClientExamples
     end
 
     def init
-      thorough? ? with_error_handling("#{initialization}api.setup\n") : initialization
+      thorough? ? with_error_handling("#{client_initialization}api.setup\n") : initialization
     end
 
     def auth_login_literal(name, parameter, value)
@@ -65,13 +73,13 @@ module HaveAPI::ClientExamples
                    end
                  RUBY
                end
-               %(#{code.chomp}\n\n# Reuse an existing token\napi.authenticate(:token, token: 'example-token'))
+               %(#{code.chomp}\n\n#{comment_lines(example_comment('reuse_token', default: 'Reuse an existing token'), '# ')}\napi.authenticate(:token, token: 'example-token'))
              when :oauth2
-               return '# OAuth2 is not supported by HaveAPI Ruby client.'
+               return comment_lines(example_comment('ruby_oauth_unsupported', default: 'OAuth2 is not supported by HaveAPI Ruby client.'), '# ')
              end
       return unless body
 
-      source = [initialization.chomp, (thorough? ? 'api.setup' : nil), body].compact.join("\n\n")
+      source = [(thorough? ? client_initialization : initialization).chomp, (thorough? ? 'api.setup' : nil), body].compact.join("\n\n")
       thorough? ? with_error_handling(source) : source
     rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
       { status: :limitation, reason: e.message }.freeze
@@ -84,7 +92,7 @@ module HaveAPI::ClientExamples
       return "api.authenticate(:token, token: 'example-token')\n" if providers.include?('token')
       return "api.authenticate(:basic, user: 'user', password: 'secret')\n" if providers.include?('basic')
 
-      raise HaveAPI::ClientExample::UnsupportedAuthentication, 'This action requires authentication unsupported by this client.'
+      raise HaveAPI::ClientExample::UnsupportedAuthentication, HaveAPI.t('haveapi.documentation.limitations.action_authentication')
     end
 
     def example(sample)
@@ -104,9 +112,9 @@ module HaveAPI::ClientExamples
       out << if sample[:status]
                response(sample)
              else
-               "\n# Raises exception HaveAPI::Client::ActionFailed\n"
+               "\n#{comment_lines(example_comment('raises_exception', default: 'Raises exception %{exception}', exception: 'HaveAPI::Client::ActionFailed'), '# ')}\n"
              end
-      thorough? ? with_error_handling(["#{initialization}api.setup", credentials.chomp, out].reject(&:empty?).join("\n\n")) : out
+      thorough? ? with_error_handling(["#{client_initialization}api.setup", credentials.chomp, out].reject(&:empty?).join("\n\n")) : out
     rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
       { status: :limitation, reason: e.message }.freeze
     end
@@ -116,17 +124,17 @@ module HaveAPI::ClientExamples
 
       case action[:output][:layout]
       when :hash
-        out << "# reply is an instance of HaveAPI::Client::Response\n"
-        out << "# reply.response() returns a hash of output parameters:\n"
+        out << "#{comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: 'reply', type: 'HaveAPI::Client::Response'), '# ')}\n"
+        out << "#{comment_lines(example_comment('response_hash', default: '%{call} returns a hash of output parameters:', call: 'reply.response()'), '# ')}\n"
         out << PP.pp(sample[:response] || {}, '').split("\n").map { |v| "# #{v}" }.join("\n")
 
       when :hash_list
-        out << "# reply is an instance of HaveAPI::Client::Response\n"
-        out << "# reply.response() returns an array of hashes:\n"
+        out << "#{comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: 'reply', type: 'HaveAPI::Client::Response'), '# ')}\n"
+        out << "#{comment_lines(example_comment('response_hashes', default: '%{call} returns an array of hashes:', call: 'reply.response()'), '# ')}\n"
         out << PP.pp(sample[:response] || [], '').split("\n").map { |v| "# #{v}" }.join("\n")
 
       when :object
-        out << "# reply is an instance of HaveAPI::Client::ResourceInstance\n"
+        out << "#{comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: 'reply', type: 'HaveAPI::Client::ResourceInstance'), '# ')}\n"
 
         (sample[:response] || {}).each do |pn, pv|
           param = action[:output][:parameters][pn]
@@ -149,8 +157,8 @@ module HaveAPI::ClientExamples
         end
 
       when :object_list
-        out << "# reply is an instance of HaveAPI::Client::ResourceInstanceList,\n"
-        out << '# which is a subclass of Array'
+        out << "#{comment_lines(example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: 'reply', type: 'HaveAPI::Client::ResourceInstanceList'), '# ')},\n"
+        out << comment_lines(example_comment('array_subclass', default: 'which is a subclass of Array'), '# ')
       end
 
       out

data/lib/haveapi/client_examples/rust_client.rb

@@ -33,7 +33,7 @@ module HaveAPI::ClientExamples
 
     def render_rust(kind, rendering_context: context, **)
       unless self.class.available?(rendering_context)
-        return { status: :limitation, reason: 'A Rust API client documentation profile is required.' }.freeze
+        return { status: :limitation, reason: HaveAPI.t('haveapi.documentation.limitations.rust_profile') }.freeze
       end
 
       rendering_context.profile.adapter.render(kind:, context: rendering_context, mode: rust_mode, **)

data/lib/haveapi/client_examples/ts_generated_client.rb

@@ -35,7 +35,7 @@ module HaveAPI::ClientExamples
 
     def render_documentation(kind, rendering_context: context, **)
       unless self.class.available?(rendering_context)
-        return { status: :limitation, reason: 'A TypeScript API client documentation profile is required.' }.freeze
+        return { status: :limitation, reason: HaveAPI.t('haveapi.documentation.limitations.typescript_profile') }.freeze
       end
 
       rendering_context.profile.adapter.render(kind:, context: rendering_context, mode: :async, **)

data/lib/haveapi/documentation_context.rb

@@ -1,15 +1,16 @@
 require 'haveapi/client_example'
+require 'haveapi/i18n'
 
 module HaveAPI
   class ClientExample
     # A request-local snapshot: never freeze or retain the server's shared help.
     class Context
-      FIELDS = %i[version host base_url version_url description resource_path resource action_name action sample profile detail].freeze
+      FIELDS = %i[version host base_url version_url description resource_path resource action_name action sample profile detail locale].freeze
       attr_reader(*FIELDS)
 
       def initialize(version:, host:, base_url:, version_url:, description:,
                      resource_path: [], resource: nil, action_name: nil, action: nil,
-                     sample: nil, profile: nil, detail: :simple)
+                     sample: nil, profile: nil, detail: :simple, locale: :en)
         @version = normalize(:version, version)
         @host = normalize(:host, host)
         @base_url = normalize(:base_url, base_url)
@@ -22,6 +23,7 @@ module HaveAPI
         @sample = normalize(:sample, sample)
         @profile = normalize(:profile, profile)
         @detail = normalize(:detail, detail)
+        @locale = normalize(:locale, locale)
         freeze
       end
 
@@ -44,6 +46,14 @@ module HaveAPI
         derived.freeze
       end
 
+      def documentation_message(key, default:, **values)
+        ::I18n.t("haveapi.documentation.#{key}", locale:, default:, **values)
+      end
+
+      def example_comment(key, default:, **values)
+        documentation_message("comments.#{key}", default:, **values)
+      end
+
       private
 
       def normalize(field, value)
@@ -54,6 +64,8 @@ module HaveAPI
           copy(value.map(&:to_s))
         when :action_name
           value.nil? ? nil : value.to_s.dup.freeze
+        when :locale
+          value.to_sym
         when :profile
           value
         when :detail