You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+38-85Lines changed: 38 additions & 85 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,122 +2,75 @@
2
2
3
3
# TranslateKit SDK
4
4
5
-
The TranslateKit SDK is a Swift package that streamlines the localization workflow in Xcode by providing:
5
+
What SF Symbols is for Icons, TranslateKit is for Text!
6
6
7
-
1.**Common Platform-Consistent Translations**: An enum with a rich set of consistently localized texts covering a large variety of typical app content - no need to localize everything yourself!
8
-
2.**Semantic Key Generation**: A Swift macro that automatically generates meaningful translation keys based on code context, while leveraging Xcode's String Catalogs.
7
+
Eliminate localization overhead in your Swift apps with 1000+ pre-localized strings and semantic key generation. Make app localization simple, accurate, and delightful.
9
8
10
-
## Features
9
+
## Key Features
11
10
12
-
### Common Translations
13
-
14
-
TranslateKit provides over 1,000 strings in four categories, already localized to all ~40 languages supported by Apple platforms:
15
-
16
-
-**Actions** (`TK.Action`): Interactive UI elements (e.g. "Done", "Add", "Cancel")
17
-
-**Labels** (`TK.Label`): Non-interactive text that describes UI elements like (e.g. "Settings", "Yes", "Link")
18
-
-**Placeholders** (`TK.Placeholder`): Temporary text while loading or waiting for user input (e.g. "Enter email…", "Loading…", "e.g. [email protected]")
19
-
-**Messages** (`TK.Message`): Full sentences for user communication (e.g. "Are you sure?", "Please try again.")
20
-
21
-
Since these strings are pre-localized, using them won't add any entries to your String Catalog. Just use them directly:
11
+
### 1. Pre-localized Common Strings
12
+
Access 1,000+ ready-to-use strings in ~40 Apple platform languages across four categories. Since these are pre-localized, they won't add entries to your String Catalog – just use them directly:
22
13
23
14
```swift
24
-
Button(TK.Action.save) { // "Save" in English, "Sichern" in German, etc.
Text(TK.Message.anErrorOccurred) // "An Error Occurred" → "Ein Fehler ist aufgetreten"
39
27
```
40
28
41
-
Discovering the right translations during programming is easy thanks to autocompletion:
42
-
1. Just type `TK.` to get the list of the 4 supported categories and select one, e.g. `Action` or `Label`
43
-
2. Now enter what you're looking for, for example type `acc` to get fuzzy-matched results like `accept`, `grantAccess`, and `addAccount`
44
-
3. Note that before you select an entry, you can see both the English translation and a usage hint in the documentation popover
29
+
Discovering the right translations is effortless with autocompletion – type `TK.` to explore categories and fuzzy-match strings, with English previews and usage hints in the documentation popover:
45
30
46
31
47
32
48
-
Super convenient, right?
49
-
50
-
### Smart Key Generation with `#tk` Macro
51
-
52
-
For your own translations, the TranslateKit SDK provides the `#tk` macro that automatically generates semantic keys based on the context:
33
+
### 2. Smart Key Generation
34
+
The `#tk` macro eliminates the tedious work of manual key management by automatically generating semantic keys based on code context:
// Short 'c' parameter for a comment providing additional context (when needed)
64
-
Text(#tk("Save changes to \(documentName)?", c: "e.g. 'Save changes to MyNumbers.csv'"))
65
-
}
66
-
}
67
-
```
68
-
69
-
The macro expands the above two `#tk` macros to proper auto-extractable String Catalog code:
70
-
71
-
```swift
72
-
structSettingsView: View {
73
-
let documentName: String
38
+
let documentName: String
74
39
75
-
var body: some View {
76
-
Button(
77
-
String(
78
-
localized: "SettingsView.Body.saveChanges",
79
-
defaultValue: "Save Changes"
80
-
)
81
-
) {
82
-
handleSave()
83
-
}
40
+
var body: some View {
41
+
// Generates key: SettingsView.Body.saveChanges
42
+
Button(#tk("Save Changes")) { handleSave() }
84
43
85
-
Text(
86
-
String(
87
-
localized: "SettingsView.Body.saveChangesTo",
88
-
defaultValue: "Save changes to \(documentName)?",
89
-
comment: "e.g. 'Save changes to Talk.keynote'"
90
-
)
91
-
)
92
-
}
44
+
// Add context with 'c' parameter to help translators
45
+
Text(#tk("Save changes to \(documentName)?",
46
+
c: "e.g. 'Save changes to MyNumbers.csv'"))
47
+
}
93
48
}
94
49
```
95
50
96
-
Note that String Catalogs support a separate "key" AND separate "source" translation, just like Strings files did back in the day. But due to how extraction is happening from baked-in SwiftUI views, nowadays most developers end up having the key and source translation to be equal. To do this, you'd have to write the verbose `String(localized:defaultValue:comment:)`function you see in the expanded code above. And every single time, you'd need to type the key manually, adding a lot of extra thinking time and work load on the developer.
51
+
String Catalogs made it challenging to maintain best practices from the Strings-file era, where using semantic keys helped group related translations. The macro brings back this advantage while keeping String Catalogs' benefits - you get semantic keys without writing verbose `String(localized:defaultValue:comment:)`calls:
97
52
98
53
99
54
100
-
That's what the `#tk` macro solves, as all you need to do is to wrap your source translation String literal in `#tk("...")`and the macro takes care of giving your translation key a proper semantic name like `SettingsView.Body.saveChanges`. This added context can be helpful for both human translators and AI translation tools (like the [TranslateKit Mac app](https://translatekit.app))to understan the context better and provide more accurate contextual translations.
55
+
These semantic keys help group related translations and provide crucial context to translators and translation tools (like the [TranslateKit Mac app](https://translatekit.app)), leading to more accurate translations while making your localization files easier to maintain.
101
56
102
-
## Using in Swift Packages
57
+
## Swift Package Usage
103
58
104
-
If you want to use TranslateKit in a Swift package or modularized app, use `#tkm` instead of `#tk`. It works exactly the same but uses `Bundle.module`to reference the correct String Catalog file in the expanded code. Full instructions to localize a Swift package:
59
+
For Swift packages, use `#tkm` instead of `#tk`to reference the correct String Catalog file:
105
60
106
-
1. Add `defaultLocalization` to your package manifest:
61
+
1. Add defaultLocalization to your manifest:
107
62
```swift
108
63
.target(
109
-
name: "MyModule",
110
-
defaultLocalization: "en",
111
-
// ...
64
+
name: "MyModule",
65
+
defaultLocalization: "en"
112
66
)
113
67
```
114
68
115
-
2. Add a String Catalog (`Localizable.xcstrings`) to your module
69
+
2. Add `Localizable.xcstrings` to your module
116
70
117
-
3. Use the `#tkm` macro instead of `#tk`:
71
+
3. Use the `#tkm` macro:
118
72
```swift
119
73
Text(#tkm("Last seen %@", c: "Time when user was last active"))
120
-
// Expands to use 'bundle: .module' rather than the main bundle
121
74
```
122
75
123
76
## Contributing
@@ -149,11 +102,11 @@ I created this library for my own Indie apps (download & rate them to thank me!)
149
102
<strong>TranslateKit: App Localizer</strong>
150
103
</a>
151
104
<br />
152
-
Indie-focused app localization with unmatched accuracy. Fast & easy: AI & proofreading, 125+ languages, market insights. Budget-friendly, free to try.
105
+
AI-powered app localization with unmatched accuracy. Fast & easy: AI & proofreading, 125+ languages, market insights. Budget-friendly, free to try.
0 commit comments