Make attributes localizable (#174)

* Make the placeholder attribute localizable

* Make the alternate attribute localizable

* Make the value attribute localizable

* Make the title attribute localizable

* Make the content attribute localizable

* Disfavor the designated functions

* Add support for verbatim content

Author: mattesmohr

Sources/HTMLKit/Abstraction/Attributes/BasicAttributes.swift

@@ -97,26 +97,65 @@ extension ActionAttribute where Self: EmptyNode {
 @_documentation(visibility: internal)
 public protocol AlternateAttribute: Attribute {
 
-    /// The function represents the html-attribute 'alt'.
+    /// Provide an alternative information
     ///
-    /// ```html
-    /// <tag alt="" />
+    /// ```swift
+    /// Image()
+    ///     .alternate("Lorem ipsum...")
     /// ```
+    ///
+    /// - Parameter value: The text to describe the image
+    ///
+    /// - Returns: The element
     func alternate(_ value: String) -> Self
+    
+    /// Provide an alternative information
+    /// 
+    /// ```swift
+    /// Image()
+    ///     .alternate("Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter localizedKey: The string key to be translated
+    /// - Parameter tableName: The translation table to look in
+    ///
+    /// - Returns: The element
+    func alternate(_ localizedKey: LocalizedStringKey, tableName: String?) -> Self
+    
+    /// Provide an alternative information without localization.
+    ///
+    /// ```swift
+    /// Image()
+    ///     .alternate(verbatim: "Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter value: The text to describe the image
+    ///
+    /// - Returns: The element
+    func alternate(verbatim value: String) -> Self
+    
 }
 
 extension AlternateAttribute where Self: ContentNode {
 
     internal func mutate(alternate value: String) -> Self {
         return self.mutate(key: "alt", value: value)
     }
+    
+    internal func mutate(alternate value: LocalizedString) -> Self {
+        return self.mutate(key: "alt", value: value)
+    }
 }
 
 extension AlternateAttribute where Self: EmptyNode {
 
     internal func mutate(alternate value: String) -> Self {
         return self.mutate(key: "alt", value: value)
     }
+    
+    internal func mutate(alternate value: LocalizedString) -> Self {
+        return self.mutate(key: "alt", value: value)
+    }
 }
 
 /// The protocol provides the element with the asynchronously handler.
@@ -430,26 +469,67 @@ extension ColumnSpanAttribute where Self: EmptyNode {
 @_documentation(visibility: internal)
 public protocol ContentAttribute: Attribute {
 
-    /// The function represents the html-attribute 'content'.
+    /// Supply a value to the associated name.
     ///
-    /// ```html
-    /// <tag content="" />
+    /// ```swift
+    /// Meta()
+    ///     .name(.description)
+    ///     .content("Lorem ipsum...")
     /// ```
+    ///
+    /// - Parameter value: The value to describe the name
+    ///
+    /// - Returns: The element
     func content(_ value: String) -> Self
+    
+    /// Supply a value to the associated name.
+    ///
+    /// ```swift
+    /// Meta()
+    ///     .name(.description)
+    ///     .content("Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter localizedKey: The string key to be translated
+    /// - Parameter tableName: The translation table to look in
+    ///
+    /// - Returns: The element
+    func content(_ localizedKey: LocalizedStringKey, tableName: String?) -> Self
+    
+    /// Supply a value to the associated name without localization
+    ///
+    /// ```swift
+    /// Meta()
+    ///     .name(.description)
+    ///     .content(verbatim: "Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter value: The value to describe the name
+    ///
+    /// - Returns: The element
+    func content(verbatim value: String) -> Self
 }
 
 extension ContentAttribute where Self: ContentNode {
 
     internal func mutate(content value: String) -> Self {
         return self.mutate(key: "content", value: value)
     }
+    
+    internal func mutate(content value: LocalizedString) -> Self {
+        return self.mutate(key: "content", value: value)
+    }
 }
 
 extension ContentAttribute where Self: EmptyNode {
 
     internal func mutate(content value: String) -> Self {
         return self.mutate(key: "content", value: value)
     }
+    
+    internal func mutate(content value: LocalizedString) -> Self {
+        return self.mutate(key: "content", value: value)
+    }
 }
 
 /// The protocol provides the element with the iseditable handler.
@@ -1913,26 +1993,64 @@ extension PingAttribute where Self: EmptyNode {
 @_documentation(visibility: internal)
 public protocol PlaceholderAttribute: Attribute {
 
-    /// The function represents the html-attribute 'placeholder'.
+    /// Supply a short hint.
     ///
-    /// ```html
-    /// <tag placeholder="" />
+    /// ```swift
+    /// Input()
+    ///     .placeholder("Lorem ipsum...")
     /// ```
+    ///
+    /// - Parameter value: The text to display as a hint
+    ///
+    /// - Returns: The element
     func placeholder(_ value: String) -> Self
+    
+    /// Supply a short hint.
+    /// 
+    /// ```swift
+    /// Input()
+    ///     .placeholder("Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter localizedKey: The string key to be translated
+    /// - Parameter tableName: The translation table to look in
+    ///
+    /// - Returns: The element
+    func placeholder(_ localizedKey: LocalizedStringKey, tableName: String?) -> Self
+    
+    /// Supply a short hint without localization.
+    ///
+    /// ```swift
+    /// Input()
+    ///     .placeholder(verbatim: "Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter value: The text to display as a hint
+    ///
+    /// - Returns: The element
+    func placeholder(verbatim value: String) -> Self
 }
 
 extension PlaceholderAttribute where Self: ContentNode {
 
     internal func mutate(placeholder value: String) -> Self {
         return self.mutate(key: "placeholder", value: value)
     }
+    
+    internal func mutate(placeholder value: LocalizedString) -> Self {
+        return self.mutate(key: "placeholder", value: value)
+    }
 }
 
 extension PlaceholderAttribute where Self: EmptyNode {
 
     internal func mutate(placeholder value: String) -> Self {
         return self.mutate(key: "placeholder", value: value)
     }
+    
+    internal func mutate(placeholder value: LocalizedString) -> Self {
+        return self.mutate(key: "placeholder", value: value)
+    }
 }
 
 /// The protocol provides the element with the poster handler.
@@ -2645,26 +2763,70 @@ extension TargetAttribute where Self: EmptyNode {
 @_documentation(visibility: internal)
 public protocol TitleAttribute: Attribute {
 
-    /// The function represents the html-attribute 'title'.
+    /// Supply extra information about the element.
     ///
-    /// ```html
-    /// <tag title="" />
+    /// ```swift
+    /// Paragraph {
+    ///     "Lorem ipsum..."
+    /// }
+    /// .title("Lorem ipsum")
     /// ```
+    ///
+    /// - Parameter value: The extra information to display
+    ///
+    /// - Returns: The element
     func title(_ value: String) -> Self
+    
+    /// Supply extra information about the element..
+    /// 
+    /// ```swift
+    /// Paragraph {
+    ///     "Lorem ipsum..."
+    /// }
+    /// .title("Lorem ipsum")
+    /// ```
+    ///
+    /// - Parameter localizedKey: The string key to be translated
+    /// - Parameter tableName: The translation table to look in
+    ///
+    /// - Returns: The element
+    func title(_ localizedKey: LocalizedStringKey, tableName: String?) -> Self
+    
+    /// Supply extra information about the element without localization.
+    ///
+    /// ```swift
+    /// Paragraph {
+    ///     "Lorem ipsum..."
+    /// }
+    /// .title(verbatim: "Lorem ipsum")
+    /// ```
+    ///
+    /// - Parameter value: The extra information to display
+    ///
+    /// - Returns: The element
+    func title(verbatim value: String) -> Self
 }
 
 extension TitleAttribute where Self: ContentNode {
 
     internal func mutate(title value: String) -> Self {
         return self.mutate(key: "title", value: value)
     }
+    
+    internal func mutate(title value: LocalizedString) -> Self {
+        return self.mutate(key: "title", value: value)
+    }
 }
 
 extension TitleAttribute where Self: EmptyNode {
 
     internal func mutate(title value: String) -> Self {
         return self.mutate(key: "title", value: value)
     }
+    
+    internal func mutate(title value: LocalizedString) -> Self {
+        return self.mutate(key: "title", value: value)
+    }
 }
 
 /// The protocol provides the element with the translate handler.
@@ -2760,26 +2922,67 @@ extension UseMapAttribute where Self: EmptyNode {
 @_documentation(visibility: internal)
 public protocol ValueAttribute: Attribute {
 
-    /// The function represents the html-attribute 'value'.
+    /// Set a initial value for the element.
     ///
-    /// ```html
-    /// <tag value="" />
+    /// ```swift
+    /// Input()
+    ///     .type(.text)
+    ///     .value("Lorem ipsum...")
     /// ```
+    ///
+    /// - Parameter value: The initial value
+    ///
+    /// - Returns: The element
     func value(_ value: String) -> Self
+    
+    /// Set a initial value for the element.
+    /// 
+    /// ```swift
+    /// Input()
+    ///     .type(.text)
+    ///     .value("Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter localizedKey: The string key to be translated
+    /// - Parameter tableName: The translation table to look in
+    ///
+    /// - Returns: The element
+    func value(_ localizedKey: LocalizedStringKey, tableName: String?) -> Self
+    
+    /// Set a initial value for the element without localization.
+    ///
+    /// ```swift
+    /// Input()
+    ///     .type(.text)
+    ///     .value(verbatim: "Lorem ipsum...")
+    /// ```
+    ///
+    /// - Parameter value: The initial value
+    ///
+    /// - Returns: The element
+    func value(verbatim value: String) -> Self
 }
 
 extension ValueAttribute where Self: ContentNode {
 
     internal func mutate(value: String) -> Self {
         return self.mutate(key: "value", value: value)
     }
+    
+    internal func mutate(value: LocalizedString) -> Self {
+        return self.mutate(key: "value", value: value)
+    }
 }
 
 extension ValueAttribute where Self: EmptyNode {
 
     internal func mutate(value: String) -> Self {
         return self.mutate(key: "value", value: value)
     }
+    
+    internal func mutate(value: LocalizedString) -> Self {
+        return self.mutate(key: "value", value: value)
+    }
 }
 
 /// The protocol provides the element with the width handler.

Sources/HTMLKit/Abstraction/Elements/BasicElements.swift

@@ -185,10 +185,19 @@ extension Html: GlobalAttributes, GlobalEventAttributes {
         return mutate(tabindex: value)
     }
 
+    @_disfavoredOverload
     public func title(_ value: String) -> Html {
         return mutate(title: value)
     }
 
+    public func title(_ localizedKey: LocalizedStringKey, tableName: String? = nil) -> Html {
+        return mutate(title: LocalizedString(key: localizedKey, table: tableName))
+    }
+    
+    public func title(verbatim value: String) -> Html {
+        return mutate(title: value)
+    }
+    
     public func translate(_ value: Values.Decision) -> Html {
         return mutate(translate: value.rawValue)
     }