summaryrefslogtreecommitdiff
path: root/framework/I18N/core/IMessageSource.php
blob: e7ed2dc7881aa50470f213c2edb3647d287fc239 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
<?php

/**
 * IMessageSource interface file.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the BSD License.
 *
 * Copyright(c) 2004 by Qiang Xue. All rights reserved.
 *
 * To contact the author write to {@link mailto:qiang.xue@gmail.com Qiang Xue}
 * The latest version of PRADO can be obtained from:
 * {@link http://prado.sourceforge.net/}
 *
 * @author Wei Zhuo <weizhuo[at]gmail[dot]com>
 * @package Prado\I18N\core
 */
 
namespace Prado\I18N\core;

/**
 * IMessageSource interface.
 * 
 * All messages source used by MessageFormat must be of IMessageSource.
 * It defines a set of operations to add and retrive messages from the
 * message source. In addition, message source can load a particular 
 * catalogue.
 *
 * @author Xiang Wei Zhuo <weizhuo[at]gmail[dot]com>
 * @package Prado\I18N\core
 */
interface IMessageSource
{
	/**
	 * Load the translation table for this particular catalogue.
	 * The translation should be loaded in the following order.
	 *  # [1] call getCatalogeList($catalogue) to get a list of 
	 *    variants for for the specified $catalogue.
	 *  # [2] for each of the variants, call getSource($variant)
	 *    to get the resource, could be a file or catalogue ID.
	 *  # [3] verify that this resource is valid by calling isValidSource($source)
	 *  # [4] try to get the messages from the cache
	 *  # [5] if a cache miss, call load($source) to load the message array
	 *  # [6] store the messages to cache.
	 *  # [7] continue with the foreach loop, e.g. goto [2].
	 * 
	 * @param string a catalogue to load
	 * @return boolean true if loaded, false otherwise.
	 */
	function load($catalogue = 'messages');	
	
	/**
	 * Get the translation table. This includes all the loaded sections.
	 * It must return a 2 level array of translation strings.
	 * # "catalogue+variant" the catalogue and its variants.
	 * # "source string" translation keys, and its translations.
	 * <code>
	 *   array('catalogue+variant' => 
	 *       array('source string' => 'target string', ...)
	 *             ...),
	 *        ...);
	 * </code>
	 * 
	 * @return array 2 level array translation table.
	 */
	function read();
	
	/**
	 * Save the list of untranslated blocks to the translation source. 
	 * If the translation was not found, you should add those
	 * strings to the translation source via the <b>append()</b> method.
	 * @param string the catalogue to add to
	 * @return boolean true if saved successfuly, false otherwise.
	 */
	function save($catalogue='messages');	
	
	/**
	 * Add a untranslated message to the source. Need to call save()
	 * to save the messages to source.
	 * @param string message to add
	 * @return void
	 */
	function append($message);
	
	/**
	 * Delete a particular message from the specified catalogue.
	 * @param string the source message to delete.
	 * @param string the catalogue to delete from.
	 * @return boolean true if deleted, false otherwise. 
	 */
	function delete($message, $catalogue='messages');
		
	/**
	 * Update the translation.
	 * @param string the source string.
	 * @param string the new translation string.
	 * @param string comments
	 * @param string the catalogue of the translation.
	 * @return boolean true if translation was updated, false otherwise. 
	 */	
	function update($text, $target, $comments, $catalogue='messages');
	
	/**
	 * Returns a list of catalogue as key and all it variants as value.
	 * @return array list of catalogues 
	 */
	function catalogues();
		
	/**
	 * Set the culture for this particular message source.
	 * @param string the Culture name.
	 */
	function setCulture($culture);
	
	/**
	 * Get the culture identifier for the source.
	 * @return string culture identifier. 
	 */
	function getCulture();	
		
}