diff --git a/docs/accessibility-guidelines.md b/docs/accessibility-guidelines.md index a385cb7ce1d6..e571e9a641bf 100644 --- a/docs/accessibility-guidelines.md +++ b/docs/accessibility-guidelines.md @@ -8,6 +8,12 @@ This is a short recap of the most important points for a successful implementati We also have a fast guide on [how to use VoiceOver](using-voiceover.md) ## Dynamic type + +### Testing considerations + +Verify how UI changes look with the system font set to larger and smaller sizes. Also try system-wide bold text. + +### Coding considerations - Avoid constraining the height of a `UILabel`, `UIButton`, or any view that has a `UILabel` or a `UIButton` as a child view. - In cases where a minimum height is necessary, use a constraint relation`greaterThanOrEqualTo`. - In most cases for `UIButton` instances, setting `.contentEdgeInsets` top and bottom will be enough to get a minimum height. @@ -25,8 +31,16 @@ We also have a fast guide on [how to use VoiceOver](using-voiceover.md) Be careful with [static tables.](dynamic-type-guidelines.md#the-static-tableview-case) +## Increased contrast + +Verify how UI changes look with the system-wide high contrast. + ## VoiceOver - To test the new (or modified) UI with VoiceOver is the best we can do to ensure a good adoption of this feature. - Add accessibility labels to elements with not enough text-based information (i.e a button with just a number or an image). -- For complex UI elements that represent one unit of information, make that unit a single VoiceOver element with a label that explains its content as we would explain it to another person. \ No newline at end of file +- For complex UI elements that represent one unit of information, make that unit a single VoiceOver element with a label that explains its content as we would explain it to another person. + +## Dark mode + +Verify how UI changes look in light and dark modes. \ No newline at end of file diff --git a/docs/localization.md b/docs/localization.md index 385b9d9177c4..530cb3bb9de1 100644 --- a/docs/localization.md +++ b/docs/localization.md @@ -1,10 +1,12 @@ # Localization +## Technical consideraations + During development, using [`NSLocalizedString()`](https://developer.apple.com/documentation/foundation/nslocalizedstring) in the code should be enough. You shouldn't need to touch the `Localizable.strings` files manually. During the release process, `NSLocalizedString` statements are scanned and stored in the `Localizable.strings` file. The file is then uploaded to [GlotPress](https://translate.wordpress.org/projects/apps/ios/) for translation. Before the release build is finalized, all the translations are grabbed from GlotPress and saved back to the `Localizable.strings` files. -## Use unique reverse-DNS naming style Keys +### Use unique reverse-DNS naming style Keys Use unique reverse-DNS naming style for keys of localized strings (instead of using the English copy as key). This allows to avoid issues where the same word in English could need different translations based on context, or very long keys causing issues with some translation services. @@ -20,7 +22,7 @@ let postBtnTitle = NSLocalizedString("Post", comment: "Verb. Action to publish a let postType = NSLocalizedString("Post", comment: "Noun. Describes when an entry is a blog post (and not story or page)" ``` -## Always add Comments +### Always add Comments Always add a meaningful comment. If possible, describe where and how the string will be used. If there are placeholders, describe what each placeholder is. @@ -44,7 +46,7 @@ let succeededMessage = String(format: NSLocalizedString( Comments help give more context to translators. -## Use positional placeholders +### Use positional placeholders Use the `%n$x` format (with `n` being an integer for the parameter position/index in the arguments to `String(format:)`, and `x` being one of the type specifiers like `@` or `d`); in particular, don't use just `%x` (the one without explicit positional index) for positional placeholders. This way, translators will not risk of messing up the parameter resolution order when translating the copy in locales where the order of the words in the sentence might be different than the one in English. @@ -66,7 +68,7 @@ let alertWarning = String(format: NSLocalizedString( ), accountName, locationName) ``` -## Do not use Variables +### Do not use Variables Do not use variables as the argument of `NSLocalizedString()` (neither for the key, the value or the comment). The string key, value and comment will not be automatically picked up by the `genstrings` tool which expects string literals. @@ -86,7 +88,7 @@ let comment = "Put a meaningful comment here." myTextLabel?.text = NSLocalizedString("some.place.title", value: "This is the text I want to translate.", comment: comment) ``` -## Do not use Interpolated Strings +### Do not use Interpolated Strings Interpolated strings are harder to understand by translators and they may end up translating/changing the variable name, causing a crash. @@ -105,7 +107,7 @@ let year = 2019 let str = NSLocalizedString("mysite.copyrightNotice.title", value: "© \(year) Acme, Inc.", comment: "Copyright Notice") ``` -## Multiline Strings +### Multiline Strings For readability, you can split the string and concatenate the parts using the plus (`+`) symbol. @@ -132,7 +134,7 @@ NSLocalizedString( ) ``` -## Pluralization +### Pluralization GlotPress currently does not support pluralization using the [`.stringsdict` file](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html#//apple_ref/doc/uid/10000171i-CH5-SW10). So, right now, you have to support plurals manually by having separate localized strings. @@ -148,10 +150,14 @@ struct PostCountLabels { let postCountText = (count == 1 ? PostCountLabels.singular : PostCountLabels.plural) ``` -## Numbers +### Numbers Localize numbers whenever possible. ```swift let localizedCount = NumberFormatter.localizedString(from: NSNumber(value: count), number: .none) -``` \ No newline at end of file +``` + +## Testing considerations + +Test changes that include localized content by using large words or with letters/accents not frequently used in English. \ No newline at end of file diff --git a/docs/pull-request-guidelines.md b/docs/pull-request-guidelines.md index 27e138ab532f..6c4c98677320 100644 --- a/docs/pull-request-guidelines.md +++ b/docs/pull-request-guidelines.md @@ -18,7 +18,7 @@ When you are ready, please, spend time crafting a good Pull Request, since it wi **Description**: Take the time to write a good summary. Why is it needed? What does it do? When fixing bugs try to avoid just writing “See original issue” – clarify what the problem was and how you’ve fixed it. -**Testing instructions**: Step by step testing instructions. When necessary break out individual scenarios that need testing, consider including a checklist for the reviewer to go through. +**Testing instructions**: Step by step testing instructions. When necessary break out individual scenarios that need testing, consider including a checklist for the reviewer to go through. Consider whether the change warrants accessibility testing. For UI changes, consider testing on different form factors (iPad, iPhone, iPad split screen) and in landscape and portrait orientations. **Images and Gif**: Include before and after images or gifs when appropriate. diff --git a/docs/right-to-left-layout-support-guidelines.md b/docs/right-to-left-layout-support-guidelines.md index dff7e52a3465..49f7113809ad 100644 --- a/docs/right-to-left-layout-support-guidelines.md +++ b/docs/right-to-left-layout-support-guidelines.md @@ -2,6 +2,8 @@ Supporting right to left layout is fairly simple and most of the hard work has already been done by Apple. +## Technical considerations + Here are a few tips to ensure this implementation is flawless throughout the app: * Avoid using `.textAlignment = .left/.right` in favor of `.natural` @@ -31,4 +33,8 @@ The problem arises when we want to customize the rect size for those accessory v The easiest way to counter this problem is by not overriding those methods, and instead, adding the required insets to the accessory view itself. If the requested layout is more complex, take this problem into account and test the RTL layout until it works :] -You can get ideas by looking at the `WPWalkthroughTextField` class. \ No newline at end of file +You can get ideas by looking at the `WPWalkthroughTextField` class. + +## Testing considerations + +UI changes related to copy should be tested with right-to-left languages. Even if translation isn’t complete, formatting should still respect the right-to-left layout. \ No newline at end of file