/core/externals/google-toolbox-for-mac/AppKit/GTMUILocalizer.h

 1//
 2//  GTMUILocalizer.h
 3//
 4//  Copyright 2009 Google Inc.
 5//
 6//  Licensed under the Apache License, Version 2.0 (the "License"); you may not
 7//  use this file except in compliance with the License.  You may obtain a copy
 8//  of the License at
 9//
10//  http://www.apache.org/licenses/LICENSE-2.0
11//
12//  Unless required by applicable law or agreed to in writing, software
13//  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
14//  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
15//  License for the specific language governing permissions and limitations under
16//  the License.
17//
18
19#import <Cocoa/Cocoa.h>
20
21// A class for localizing nibs by doing simple string replacement.
22// To use this, make an instance of GTMUILocalizer in your nib. Connect the
23// owner_ outlet of the your instance to the File Owner of the nib. It expects
24// the owner_ outlet to be an instance or subclass of NSWindowController,
25// NSViewController or NSApplication. Using the bundle of the nib it will then
26// localize any items in the NSWindowController's window and subviews, or the
27// NSViewController's view and subviews or the NSApplication's main menu
28// and dockmenu at when awakeFromNib is called on the GTMUILocalizer instance.
29// You can optionally hook up otherObjectToLocalize_ and
30// yetAnotherObjectToLocalize_ and those will also be localized. Strings in the
31// nib that you want localized must start with ^ (shift-6). The strings will
32// be looked up in the Localizable.strings table without the caret as the
33// key.
34// Things that will be localized are:
35//  - Titles and altTitles (for menus, buttons, windows, menuitems, tabViewItem)
36//  - stringValue (for labels)
37//  - tooltips
38//  - accessibility help
39//  - menus
40//
41// Due to technical limitations, accessibility description cannot be localized.
42// See http://lists.apple.com/archives/Accessibility-dev/2009/Dec/msg00004.html
43// and http://openradar.appspot.com/7496255 for more information.
44//
45// As an example if I wanted to localize a button with the word "Print" on
46// it, I would put it in a window controlled by a NSWindowController that was
47// the owner of the nib. I would set it's title to be "^Print". I would then
48// create an instance of GTMUILocalizer and set it's owner_ to be the owner
49// of the nib.
50// In my Localizable.strings file in my fr.lproj directory for the bundle
51// I would put "Print" = "Imprimer";
52// Then when my app launched in French I would get a button labeled
53// "Imprimer". Note that GTMUILocalizer is only for strings, and doesn't
54// resize, move or change text alignment on any of the things it modifies.
55// If you absolutely need a caret at the beginning of the string
56// post-localization, you can put "Foo" = "^Foo"; in your strings file and
57// it will work.
58// Your nib could be located in a variety of places depending on what you want
59// to do. I would recommend having your "master" nib directly in Resources.
60// If for some reason you needed to do some custom localization of the
61// nib you could copy the master nib into your specific locale folder, and
62// then you only need to adjust the items in the nib that you need to
63// customize. You can leave the strings in the "^Foo" convention and they
64// will localize properly. This keeps the differences between the nibs down
65// to the bare essentials.
66//
67// NOTE: NSToolbar localization support is limited to only working on the
68// default items in the toolbar. We cannot localize items that are on of the
69// customization palette but not in the default items because there is not an
70// API for NSToolbar to get all possible items. You are responsible for
71// localizing all non-default toolbar items by hand.
72//
73@interface GTMUILocalizer : NSObject {
74 @protected
75  IBOutlet id owner_;
76  IBOutlet id otherObjectToLocalize_;
77  IBOutlet id yetAnotherObjectToLocalize_;
78 @private
79  NSBundle *bundle_;
80}
81- (id)initWithBundle:(NSBundle *)bundle;
82
83// Localize |object|. If |recursive| is true, it will attempt
84// to localize objects owned/referenced by |object|.
85- (void)localizeObject:(id)object recursively:(BOOL)recursive;
86
87// A method for subclasses to override in case you have a different
88// way to go about getting localized strings.
89// If |string| does not start with ^ you should return nil.
90// If |string| is nil, you should return nil
91- (NSString *)localizedStringForString:(NSString *)string;
92
93// Allows subclasses to override how the bundle is picked up
94+ (NSBundle *)bundleForOwner:(id)owner;
95@end